Skip to content

NOTES

Overview

The online sensing module provides continuous sensor data acquisition and transmission functionality. It enables real-time monitoring of sensor data with configurable sampling frequency and multiple output channels (MQTT, serial, and optionally LCD).

Features

  • ✅ Configurable sampling frequency (default: 20 Hz, range: 0.1 - 10000 Hz)
  • ✅ MQTT transmission (enabled/disabled)
  • ✅ Serial output (enabled/disabled)
  • ✅ Optional LCD display (when TINY_MEASUREMENT_ENABLE_LCD is defined)
  • ✅ Fixed-rate data acquisition using ESP timer
  • ✅ Automatic data formatting
  • ✅ Thread-safe operation
  • ✅ Runtime configuration updates

Architecture

Timer-Based Sampling

The module uses ESP timer for precise periodic sampling:

  1. Timer Creation: Creates a periodic timer with period = 1 / sampling_frequency
  2. Timer Callback: Executes at each timer tick to read sensor data
  3. Data Output: Formats and outputs data to configured channels (MQTT, serial, LCD)

Data Flow

ESP Timer → Timer Callback → Sensor Read → Data Formatting → Output Channels
                                                                    ├─ MQTT
                                                                    ├─ Serial
                                                                    └─ LCD (optional)

Configuration

Default Configuration

Default values are defined in tiny_measurement_config.h:

#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_FREQ_HZ 20.0f
#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_ENABLE_MQTT true
#define TINY_MEASUREMENT_ONLINE_SENSING_DEFAULT_ENABLE_SERIAL true

Configuration Structure

typedef struct
{
    float sampling_frequency_hz;  // Sampling frequency in Hz
    bool enable_mqtt;              // Enable MQTT transmission
    bool enable_serial;            // Enable serial output
    bool enable_lcd;               // Enable LCD display (optional)
    const char *mqtt_topic;        // MQTT topic (NULL for default)
} online_sensing_config_t;

Data Format

MQTT Format

Compact format with 6 decimal places for full 20-bit precision:

x,y,z,temp

Example: 

0.012345,-0.045678,0.987654,25.50

Serial Format

Same format as MQTT, with newline:

x,y,z,temp\n

LCD Format

One axis per line: - Line 1: X:0.012345 - Line 2: Y:-0.045678 - Line 3: Z:0.987654 - Line 4: T:25.50C

Usage Workflow

  1. Initialize Sensor: Initialize ADXL355 sensor
  2. Set Sensor Handle: Call online_sensing_set_sensor_handle()
  3. Initialize Module: Call online_sensing_init() with configuration (or NULL for defaults)
  4. Start Sensing: Call online_sensing_start()
  5. Runtime Updates: Optionally update frequency or enable/disable channels
  6. Stop Sensing: Call online_sensing_stop() when done
  7. Deinitialize: Call online_sensing_deinit() to clean up

Performance Considerations

Sampling Frequency Limits

  • Minimum: 0.1 Hz (10 second period)
  • Maximum: 10000 Hz (100 microsecond period)
  • Recommended: 1 - 1000 Hz for most applications

Resource Usage

  • CPU: Timer callback executes at sampling frequency
  • Memory: Minimal stack usage in callback
  • Network: MQTT bandwidth depends on frequency and payload size
  • Serial: High frequencies may cause serial buffer overflow

Optimization Tips

  1. Disable Serial Output: For high frequencies (>100 Hz), disable serial output
  2. MQTT QoS: Use QoS 0 for high-frequency data (default)
  3. LCD Update: LCD updates are relatively slow, use only for low frequencies (<10 Hz)

Error Handling

Common Errors

  • ESP_ERR_INVALID_ARG: Invalid frequency (out of range)
  • ESP_ERR_INVALID_STATE: Already running or not initialized
  • ESP_FAIL: Timer creation or start failed

Error Recovery

  • Check sensor handle is set before starting
  • Validate frequency range before initialization
  • Stop before restarting with new configuration

Thread Safety

  • Timer callback is executed in timer context (high priority)
  • Configuration changes require stopping and restarting
  • State checks prevent concurrent operations

Integration Notes

MQTT Integration

  • Requires MQTT client to be connected
  • Checks s_is_mqtt_connected before publishing
  • Uses default topic if mqtt_topic is NULL

Sensor Integration

  • Requires ADXL355 sensor handle
  • Must be initialized before setting handle
  • Sensor read operations are non-blocking

LCD Integration

  • Only available when TINY_MEASUREMENT_ENABLE_LCD is defined
  • LCD screen is cleared when starting
  • Updates are synchronous (may affect timing at high frequencies)