Custom hardware integration

Guide for teams that ship their own PCB (no IOTMER reference board). The SDK handles cloud connectivity; you own pins, buses, and sensors.

Quick start

From any directory (ESP-IDF environment optional for scaffold):

python /path/to/iotmer-sdk-esp-idf/tools/iotmer.py create-app my-gateway --chip esp32s3 --profile field
cd my-gateway
source $IDF_PATH/export.sh
idf.py set-target esp32s3
idf.py menuconfig
idf.py build flash monitor

Validate sdkconfig before debugging TLS or OTA:

python /path/to/iotmer-sdk-esp-idf/tools/iotmer.py doctor --project .

Project layout

my-gateway/
├── components/
│   ├── hw/          ← YOU: pins, RS485, sensors, LEDs
│   └── cloud/       ← IOTMER: init, MQTT, telemetry (extend carefully)
├── main/            ← Boot order only
├── sdkconfig.defaults
├── sdkconfig.defaults.field
├── sdkconfig.defaults.factory
└── partitions_ota_4mb.csv

Layer	Responsibility
hw	hw_init(), hw_read_telemetry(), Kconfig for GPIO / peripherals
cloud	iotmer_app_start() — Wi‑Fi, provision, MQTT, command handler
main	nvs_flash_init() → hw_init() → iotmer_app_start()

Keep hardware and cloud separate so you can change PCB revisions without touching MQTT logic.

Integration checklist

Step	You do	SDK / tool
1. Scaffold	iotmer create-app	Template + sdkconfig defaults
2. Target chip	idf.py set-target <chip>	Supported: esp32, esp32c3, esp32s3, …
3. Partition / flash	Adjust partitions_*.csv if flash ≠ 4MB	doctor warns on OTA layout
4. HW bring-up	Implement hw_init.c	menuconfig → HW
5. Wi‑Fi	SSID/password in menuconfig, NVS, or BLE	iotmer_wifi_* API
6. Factory flash	--profile factory, set auth code	01_provisioning flow
7. Field flash	--profile field, empty auth code	02_telemetry flow
8. Remote config	Handler in app	04_config + iotmer_config.h
9. BLE setup (optional)	Add iotmer_ble dependency	05_ble_json
10. Pre-release	iotmer doctor	Catches TLS / stack / OTA mistakes

Dependencies

Registry (default) — for customer repos:

# idf_component.yml
dependencies:
  iotmertech/iotmer: "*"

Local SDK checkout — when developing against this monorepo:

iotmer create-app my-gateway --deps local --sdk-root /path/to/iotmer-sdk-esp-idf

Common mistakes

Symptom	Fix
TLS / mbedTLS crash on boot	CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
Certificate verify failed	Enable CONFIG_MBEDTLS_CERTIFICATE_BUNDLE (see template defaults)
OTA partition too small	Custom partitions_ota_4mb.csv or increase slot size
MQTT not authorized	Field image with empty NVS — re-provision with factory profile
Auth code in field firmware	Use factory vs field profiles

Reference examples

The numbered examples under examples/ remain the authoritative SDK behaviour reference. The create-app scaffold wraps the 02_telemetry field flow with a hw/cloud split.

Further reading

• Factory vs field profiles
• BLE JSON provisioning (scaffold)
• Platform docs: docs.iotmer.com