GetSHT31Data is an ESP-IDF C firmware application for ESP32 that samples temperature and humidity from an SHT31 sensor over I2C, serializes each reading with cJSON, buffers pending JSON payloads in RAM when Wi-Fi disconnects, and uploads measurements via HTTP POST using esp_http_client. Sensor sampling waits for SNTP clock synchronization before running a periodic 1 Hz loop with NVS-backed sequence number reservation. The sister firmware targeting a single-wire DHT11 sensor is maintained in GetDHTData.
+-------------------+ network_time_synced() +-------------------+ worker_sht_json_handler +-------------------+
| network.c | ----------------------> | read_sht_data | ---(sht_data_t, len 5)--> | sht_json_task |
| life_guard (C1,P9)| | (sht_sensor.c) | | (feature.c) |
+-------------------+ | Core 1, Prio 7 | | Core 1, Prio 7 |
| +-------------------+ +-------------------+
| wifi_event_handler |
| (BIT0 SUCCESS / BIT1 FAIL) worker_json_net_handler |
v (char *, len 5)|
+------------------------+ WIFI_CONNECT_SUCCESS +------------------------+ |
| http_upload_build() | <----- HTTP POST -------- | json_network_retrieve | <-----------------------+
| (http_build.c) | (drain cache, then Q) | (worker.c) |
+------------------------+ | Core 0, Prio 7 |
+------------------------+
| ^
WIFI_CONNECT_FAIL | | FIFO drain on
network_failed_buffer| | WIFI_CONNECT_SUCCESS
v |
+------------------------+
| json_buffer[128] |
| (feature.c, max 127) |
+------------------------+
The components/feature_extract directory (feature.c) performs cJSON object serialization of sht_data_t structs and holds the static RAM fallback array json_buffer for failed network states. It does not perform signal processing or statistical feature extraction.
| Path | Files | Responsibility |
|---|---|---|
main |
main.c, CMakeLists.txt, Kconfig |
Entry point app_main: sets global log level to ESP_LOG_WARN, initializes NVS (erasing on any error), calls network_init(), http_init(), and worker_session(). |
components/common |
common.h, CMakeLists.txt |
Header-only shared types (sht_data_t, QueueGroupHandle_t), stack size macros (NORMAL_STACKSIZE, NETWORK_STACKSIZE), JSON_BUFFER_SIZE, and custom error codes (0x10001-0x10003). |
components/sht_sensor |
sht_sensor.c, sht_sensor.h, CMakeLists.txt, Kconfig, idf_component.yml |
Initializes i2cdev and sht3x, loads and reserves NVS sequence blocks, waits for SNTP sync, polls SHT31 at 1 Hz, and pushes sht_data_t structs to worker_sht_json_handler. |
components/feature_extract |
feature.c, feature.h, CMakeLists.txt, idf_component.yml |
Reads sht_data_t from worker_sht_json_handler, builds unformatted JSON strings via cJSON, forwards pointers to worker_json_net_handler, and stores up to 127 buffered pointers in json_buffer. |
components/http_build |
http_build.c, http_build.h, CMakeLists.txt, Kconfig |
Configures a persistent esp_http_client handle for HTTP_METHOD_POST with Content-Type: application/json and retries failed transfers. |
components/network |
network.c, network.h, CMakeLists.txt, Kconfig |
Configures Wi-Fi STA mode, manages reconnect retries and the life_guard task via wifi_event_handler, initializes SNTP on IP acquisition, and sets TZ to UTC0. |
components/worker |
worker.c, worker.h, CMakeLists.txt |
Creates the two FreeRTOS queues, spawns the sensor, JSON, and network transfer tasks, and implements the json_network_retrieve dispatch and cache-drain loop. |
| Function | Task name string | Stack size (bytes) | Priority | Core ID | Queues / EventGroups |
|---|---|---|---|---|---|
life_guard |
WIFI LIFE GUARD |
4096 (NORMAL_STACKSIZE) |
9 |
1 |
Waits on wifi_event_handler (WIFI_CONNECT_FAIL) |
read_sht_data |
READ SENSOR DATA |
4096 (NORMAL_STACKSIZE) |
7 |
1 |
Sends to worker_sht_json_handler |
sht_json_task |
JSON TO NETWORK |
4096 (NORMAL_STACKSIZE) |
7 |
1 |
Receives from worker_sht_json_handler, sends to worker_json_net_handler |
json_network_retrieve |
WIFI DATA TRANSFER |
8192 (NETWORK_STACKSIZE) |
7 |
0 |
Waits on wifi_event_handler (WIFI_CONNECT_SUCCESS | WIFI_CONNECT_FAIL), receives from worker_json_net_handler |
- I2C driver API:
components/sht_sensor/sht_sensor.cuses the managed ESP Component Registry driveresp-idf-lib/sht3x(1.0.8) built onesp-idf-lib/i2cdev(2.1.2). It callsi2cdev_init(),sht3x_init_desc(),sht3x_init(), andsht3x_measure(). - I2C parameters: Port
SHT_I2C_PORT(I2C_NUM_0), 7-bit addressSHT_I2C_ADDRESS(0x44), and pinsCONFIG_I2CDEV_DEFAULT_SDA_PINandCONFIG_I2CDEV_DEFAULT_SCL_PIN(provided byesp-idf-lib/i2cdevKconfig rather than hardcoded insht_sensor.c). SHT31 command bytes and CRC checks are handled internally insideesp-idf-lib/sht3xand do not appear directly in this repository's source files. - SNTP startup gate: Before sampling starts,
read_sht_datapollsnetwork_time_synced()every200ms (vTaskDelay) and logs a warning every30000ms while time remains unsynced. - Sampling interval and timestamps: Once SNTP sync completes,
read_sht_datacapturesxTaskGetTickCount()and runs a 1 Hz loop withvTaskDelayUntil(&last_wake_time, pdMS_TO_TICKS(SHT_WAKETIME))whereSHT_WAKETIMEis1000ms. Each reading obtainsts_msin Unix epoch milliseconds viagettimeofday(&tv, NULL). - Sequence persistence:
seq_load()readsu32keySEQ_NVS_KEY("seq") from NVS namespaceSEQ_NVS_NAMESPACE(defaulting to0). To limit NVS flash writes, firmware reserves blocks ofSEQ_BLOCK(64): on boot it writessequence_number + 64to NVS, andseq_maybe_persist()commits the next+64reservation wheneversequence_number >= seq_persist_at. - Sensor error handling: If
init_sht_sensor()fails,read_sht_datalogs an error and retries on the next 1000 ms period without enqueuing a sample. Once initialized, ifsht3x_measure()fails,data_failed()enqueues a record withtemperature = 0.0f,humidity = 0.0f, andstate = false. Queue sends toworker_sht_json_handlerwait up toSHT_WAITTIME(100ms).
- FreeRTOS queues:
worker_session()allocatesworker_sht_json_handler(xQueueCreate(5, sizeof(sht_data_t))) andworker_json_net_handler(xQueueCreate(5, sizeof(char *))). - RAM fallback buffer:
feature.cdeclaresstatic char * json_buffer[JSON_BUFFER_SIZE](128).network_failed_buffer()checks(*amount_pointer) >= JSON_BUFFER_SIZE - 1, giving an effective capacity of127JSON string pointers. When127items are already buffered, incoming JSON strings are freed withcJSON_free()and dropped withESP_ERR_QUEUE_FULL. - Disconnect and drain flow:
- When
WIFI_CONNECT_FAIL(BIT1) is set inwifi_event_handler,json_network_retrievereceives pointers fromworker_json_net_handler, setsis_failed_before = true, and appends them vianetwork_failed_buffer(). - When
WIFI_CONNECT_SUCCESS(BIT0) is set andis_failed_before && queue_stored_amount != 0,json_network_retrievesends entries fromjson_buffer[real_data_position]in FIFO order viahttp_upload_build(), freeing each successfully uploaded string withcJSON_free(). Oncereal_data_position == queue_stored_amount, counters reset andis_failed_beforebecomesfalse. - When no buffered entries remain (
!is_failed_before && queue_stored_amount == 0),json_network_retrieveblocks onworker_json_net_handler, callshttp_upload_build(json_receive), and callscJSON_free(json_receive).
- When
- Wi-Fi (
components/network/network.c,network.h):- Station mode (
WIFI_MODE_STA), auth thresholdWIFI_AUTH_WPA2_PSK, PMFcapable = true,required = false. - On
WIFI_EVENT_STA_DISCONNECTED, clearsWIFI_CONNECT_SUCCESSand performs up toMAX_RETRY(3) immediateesp_wifi_connect()calls (NETWORK_WAKETIME2000is defined innetwork.hbut commented out innetwork.c). After3failed retries, setsWIFI_CONNECT_FAILand resumeslife_guard, which delaysLIFE_GUARD_WAITTIME(3000ms) before each subsequentesp_wifi_connect(). - On
IP_EVENT_STA_GOT_IP, resetscurrent_retry = 0, setsWIFI_CONNECT_SUCCESS, clearsWIFI_CONNECT_FAIL, suspendslife_guard, initializes SNTP withESP_NETIF_SNTP_DEFAULT_CONFIG(NTP_SERVER_IP)(NTP_SERVER_IPis defined as a hardcoded local IPv4 address incomponents/network/network.h), waits up to15000ms inesp_netif_sntp_sync_wait(), setstime_synced = trueonESP_OK, and configuresTZto"UTC0".
- Station mode (
- HTTP client (
components/http_build/http_build.c):- Initialized once in
http_init()with.url = CONFIG_HTTP_SERVER_URL,.method = HTTP_METHOD_POST,.timeout_ms = 4000,.buffer_size = 512,.buffer_size_tx = 512,.keep_alive_enable = true, and headerContent-Type: application/json. http_upload_build()callsesp_http_client_perform()up tomax_retry(3) total attempts consecutively with no inter-retry delay. Only HTTP status codes200 <= status_code < 300returnESP_OK; otherwise it continues up to3total attempts and returnsESP_FAIL.
- Initialized once in
CONFIG_NETWORK_SSID, CONFIG_NETWORK_PASSWORD, and CONFIG_HTTP_SERVER_URL have no defaults and must be configured in idf.py menuconfig before building.
| Symbol | File | Type | Default | Description |
|---|---|---|---|---|
CONFIG_ESP_DEBUG_LOGV |
main/Kconfig |
bool |
y |
Declared for verbose debug logging (SHOW THE INFORMATION OF DEBUG), though unused in C source. |
CONFIG_ESP_DEVICE_ID |
main/Kconfig |
string |
"ESP32_1" |
Device identifier emitted in the JSON "d_id" field. |
CONFIG_ALGORISM_VERSION |
components/sht_sensor/Kconfig |
string |
"B1" |
Algorithm/firmware version string emitted in the JSON "v" field. |
CONFIG_NETWORK_SSID |
components/network/Kconfig |
string |
(none) | Target Wi-Fi station SSID. |
CONFIG_NETWORK_PASSWORD |
components/network/Kconfig |
string |
(none) | Target Wi-Fi station password. |
CONFIG_HTTP_SERVER_URL |
components/http_build/Kconfig |
string |
(none) | HTTP POST endpoint URL passed to esp_http_client. |
I2C SDA and SCL GPIOs are configured through CONFIG_I2CDEV_DEFAULT_SDA_PIN and CONFIG_I2CDEV_DEFAULT_SCL_PIN under the managed i2cdev component menu in idf.py menuconfig.
| Setting | Value | Purpose in firmware |
|---|---|---|
CONFIG_FREERTOS_HZ |
100 |
10 ms FreeRTOS tick resolution; tickless idle is explicitly disabled. |
CONFIG_PM_ENABLE |
not set | Disables dynamic power management and DFS. |
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ |
160 |
Sets default CPU clock to 160 MHz (CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_160=y). |
CONFIG_ESP_PHY_MAX_WIFI_TX_POWER |
20 |
Caps maximum Wi-Fi TX power at 20 dBm. |
CONFIG_ESP_WIFI_AMPDU_TX_ENABLED / RX_ENABLED |
y |
Enables Wi-Fi TX/RX A-MPDU aggregation with TX_BA_WIN=6 and RX_BA_WIN=6. |
CONFIG_ESP_WIFI_STA_DISCONNECTED_PM_ENABLE |
y |
Enables STA power management while disconnected; CONFIG_ESP_WIFI_SLP_IRAM_OPT is not set. |
CONFIG_LWIP_SNTP_MAX_SERVERS |
1 |
Limits lwIP SNTP servers to 1. |
CONFIG_LWIP_SNTP_UPDATE_DELAY |
600000 |
Sets SNTP periodic resync interval to 600,000 ms (10 minutes); startup delay is disabled. |
CONFIG_LOG_DEFAULT_LEVEL |
2 (WARN) |
Compiles default log level at WARN (CONFIG_LOG_DEFAULT_LEVEL_WARN=y). |
CONFIG_ESP_CONSOLE_UART_BAUDRATE |
115200 |
UART0 console baud rate. |
CONFIG_COMPILER_OPTIMIZATION_SIZE |
y |
Enables -Os size optimization (CONFIG_COMPILER_OPTIMIZATION_DEBUG not set). |
CONFIG_LWIP_MAX_SOCKETS |
10 |
Allocates up to 10 lwIP sockets. |
feature.c serializes each sht_data_t sample with cJSON_PrintUnformatted(root) (single-line JSON on the wire; formatted below for readability):
{
"v": "B1",
"d_id": "ESP32_1",
"seq": 64,
"temp": 25.38,
"humi": 54.12,
"st": true,
"ts": 1731888000123
}| Key | cJSON builder |
Source | Type / Meaning |
|---|---|---|---|
"v" |
cJSON_AddStringToObject |
CONFIG_ALGORISM_VERSION |
String version tag |
"d_id" |
cJSON_AddStringToObject |
CONFIG_ESP_DEVICE_ID |
String device identifier |
"seq" |
cJSON_AddNumberToObject |
get_data.sequence (uint32_t) |
Monotonic sequence counter (NVS block-reserved in steps of 64) |
"temp" |
cJSON_AddNumberToObject |
get_data.temperature (float) |
Temperature in degrees Celsius (0.0 when st is false) |
"humi" |
cJSON_AddNumberToObject |
get_data.humidity (float) |
Relative humidity in percent (0.0 when st is false) |
"st" |
cJSON_AddBoolToObject |
get_data.state (uint8_t) |
Boolean read status (true on sht3x_measure ESP_OK, false on failure) |
"ts" |
cJSON_AddNumberToObject |
get_data.ts_ms (uint64_t) |
Unix epoch timestamp in milliseconds (UTC0) |
This repository contains only the ESP32 firmware; the companion HTTP JSON ingestion server is maintained in a separate repository.
The top-level CMakeLists.txt requires CMake 3.22 and defines the project name Paperdata. dependencies.lock targets esp32 on ESP-IDF 6.1.0 with managed dependencies esp-idf-lib/sht3x (1.0.8), esp-idf-lib/i2cdev (2.1.2), esp-idf-lib/esp_idf_lib_helpers (1.4.0), and espressif/cjson (1.7.19~2).
idf.py set-target esp32
idf.py menuconfig
idf.py build
idf.py -p <PORT> flash monitorIn idf.py menuconfig, configure NETWORK_CFG (NETWORK_SSID, NETWORK_PASSWORD), HTTP Setting (HTTP_SERVER_URL), ESP_MAIN_SETTING (ESP_DEVICE_ID), SHT Sensor Configuration (ALGORISM_VERSION), and the i2cdev SDA/SCL pin numbers (CONFIG_I2CDEV_DEFAULT_SDA_PIN, CONFIG_I2CDEV_DEFAULT_SCL_PIN).
- Hardcoded SNTP host and blocking callback:
NTP_SERVER_IPis hardcoded incomponents/network/network.hrather than exposed via Kconfig. Insideevent_handler(IP_EVENT_STA_GOT_IP),esp_netif_sntp_sync_wait(pdMS_TO_TICKS(15000))blocks the defaultesp_eventloop task for up to 15 seconds if the SNTP server is unreachable, and subsequent reconnects callesp_netif_sntp_init()again without callingesp_netif_sntp_deinit(). - No sampling without SNTP sync:
read_sht_dataspins onnetwork_time_synced()before entering the measurement loop, so no readings are captured or buffered if SNTP fails on startup. - Volatile RAM cache and 127-item ceiling:
json_bufferholds at most127(JSON_BUFFER_SIZE - 1)cJSONstrings in RAM. Power loss clears unsent records, and any new sample arriving while the buffer is full is freed and dropped. - No buffering for HTTP failures while Wi-Fi is connected:
json_network_retrieveonly buffers intojson_bufferwhenWIFI_CONNECT_FAIL(BIT1) is set. WhileWIFI_CONNECT_SUCCESS(BIT0) is set and the buffer is empty,cJSON_free(json_receive)is called unconditionally afterhttp_upload_build(), discarding payloads if the HTTP endpoint returns non-2xx or times out while Wi-Fi remains associated. In addition, if a cached drain fails whileWIFI_CONNECT_SUCCESSstays set, thewhileloop breaks and the outer loop immediately re-enters without backoff becausexEventGroupWaitBits(..., pdFALSE, ...)does not clearWIFI_CONNECT_SUCCESS. - Disconnect state transitions:
IP_EVENT_STA_LOST_IPresumeslife_guardwithout settingWIFI_CONNECT_FAIL, whereaslife_guardblocks onWIFI_CONNECT_FAIL(set only byWIFI_EVENT_STA_DISCONNECTEDafterMAX_RETRYfailures).current_retryis also reset only onIP_EVENT_STA_GOT_IP, so after hittingMAX_RETRYonce, reconnects rely onlife_guarduntil an IP is acquired. - NVS erase policy and runtime log clamping:
app_main()callsesp_log_level_set("*", ESP_LOG_WARN);, suppressing allESP_LOGIoutput across components regardless ofCONFIG_ESP_DEBUG_LOGV. On any non-ESP_OKreturn fromnvs_flash_init(),app_main()callsnvs_flash_erase(), wiping storedSEQ_NVS_NAMESPACE/SEQ_NVS_KEYsequence state, and does not check the secondnvs_flash_init()return code. - Unused struct fields and plain HTTP:
sht_data_tdefinesdevice_id[16]andversion[8], which are never populated (feature.creads Kconfig strings directly).http_init()does not configure TLS verification (cert_pemorcrt_bundle_attach).