FAQ

For step-by-step fixes, see Troubleshooting. For the full behavior, see Shared Concepts.

Which SDK should I use?

Match it to your platform: ESP-IDF for ESP32 firmware, C/POSIX for embedded Linux and gateways (and local development), MicroPython for MicroPython firmware, Arduino for ESP32 Arduino sketches (preview). If a device cannot reach the internet, pair it with the React Native relay. If none fit, send events directly with the HTTP API.

I sent an event. What should happen?

Initialization queues $device_boot immediately. Your track() adds an event to the local queue. On the next tick()/flush() while online, the SDK posts to /capture and Capture returns 204 (batch accepted) or 202 (chunk stored). The event then appears in your project's live events.

What endpoint do the SDKs use?

POST /capture
Content-Type: application/vnd.honch.chunk
X-Honch-Project-Key: <project_api_key>
X-Honch-Stream-Id: <stream_id>

The default host is https://i.honch.io. Direct HTTP integrations post JSON to the same /capture path.

Should I use HTTPS?

Yes, in production. The device ports verify the server certificate and provide no production way to disable it. Use plain HTTP only when intentionally talking to a local capture service during development.

What gets collected automatically?

A fixed context on every event: $device_id, $device_model, $firmware_version, $sdk_platform, $sdk_version, $environment. Conditionally: $session_id during a session, $battery_level if you supply a battery callback, and $wifi_rssi if your port supplies it. The SDK does not auto-collect heap, uptime, hardware revision, or location.

Can user properties override SDK properties?

No. If an event includes a reserved key (an SDK-owned $ key or distinct_id), the track() call is rejected with an invalid-argument error. Reserved keys are never silently overwritten — rename your property.

What property values can I pass?

Typed values: null, boolean, integer, float, string, bytes, arrays, and maps (nested). Up to 64 properties per event; event names up to 128 bytes.

Which errors are retryable?

408, 409, 429, 5xx, and transport failures are retryable — events stay queued and retry with backoff (1 s to 5 min, ±25% jitter). 401 and other 4xx are permanent; the batch is dropped or dead-lettered.

What happens when the device is offline?

Events stay queued. Supply a connectivity callback so the SDK skips DNS/TLS work while offline; when connectivity returns, queued events flush with backoff. Nothing is lost as long as the queue (RAM by default, drop-oldest past max_queued_events) has not overflowed or been cleared by a reset.

What happens on reset?

reset() clears identity, the active session, and the local queue, and emits no event. With a configured device_id, identity returns to it; otherwise the SDK generates a new random $device_id. Use it at a factory-reset or logout boundary.

Why does MicroPython need a user C module?

The MicroPython wrapper is a thin Python layer over the same C core, bound through the _honch_core user C module. The module must be compiled into your firmware — there is no pure-Python implementation. See the MicroPython guide.

Can I call track() from an ISR?

No. track() can allocate, and tick()/flush() do blocking network I/O. From an ISR, push minimal data (like a pin number) onto a queue and call track() from a normal task. See the ESP-IDF GPIO pattern.

How does the relay acknowledge a device?

Your app hands each BLE frame to the relay; the relay durably stores it and returns ACK bytes (a version byte plus a big-endian sequence number). Your app writes those bytes to the device's ACK characteristic. The relay never touches Bluetooth itself — that stays host-owned.