Honch - Quickstart

Pick your SDK below and follow the steps. The goal is one verified event — install, configure, send, and confirm it reaches Honch. Deeper configuration lives on each SDK's guide.

Set Your Capture Values

Every integration needs the same handful of values:

Value	Example	Notes
Project API key	`your-project-key`	Sent as the `X-Honch-Project-Key` header.
Device model	`demo-board`	Static per product.
Firmware version	`1.0.0`	Drives `$firmware_update` when it changes.
Environment	`production`	Optional; defaults to `production`. Use `development` for tests.

Endpoint

The capture endpoint defaults to https://i.honch.io. You only set host / endpoint_url to point elsewhere — for example a local capture service during development. The examples below pass it explicitly for clarity.

Build Your Integration

Install the component

idf.py add-dependency "honch/honch^0.3.0"

Configure and initialize

Bring up NVS, the network, Wi-Fi, and time first (your firmware's job), then initialize Honch. honch_init() is synchronous and does no network I/O.

#include "honch.h"
static uint8_t buf[16384];

honch_config_t config = {
    .api_key = CONFIG_HONCH_API_KEY,
    .host = "https://i.honch.io",
    .device_model = "demo-board",
    .firmware_version = "1.0.0",
    .event_buffer = buf,
    .event_buffer_size = sizeof(buf),
};
honch_init(&config);

Send your first event

honch_track("app_started", NULL, 0);

Keep events flowing

There is no background thread. Pump delivery from a low-priority task with at least 8192 bytes of stack:

static void honch_task(void *arg) {
    for (;;) {
        honch_tick();
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}
// xTaskCreate(honch_task, "honch", 8192, NULL, 2, NULL);

Verify

idf.py build flash monitor

Watch the log for $device_boot at init, then a POST /capture once Wi-Fi and time are up. Full guide: ESP-IDF.

Build the SDK

cmake -S . -B build -DHONCH_BUILD_EXAMPLES=ON
cmake --build build

Configure a client

Every call takes an explicit client handle, and the queue is file-backed under queue_directory.

#include "honch/honch.h"

honch_config_t config = {
    .api_key = "your-project-key",
    .endpoint_url = "https://i.honch.io",
    .device_model = "linux-gateway",
    .firmware_version = "1.0.0",
    .queue_directory = "/var/lib/honch",
};
honch_client_t *client = NULL;
honch_init(&client, &config);

Send your first event

honch_track(client, "app_started", NULL, 0);
honch_flush(client);

Keep events flowing

Pump honch_tick(client) from a dedicated thread; it does a synchronous POST and blocks up to transport_timeout_ms.

while (running) {
    honch_tick(client);
    sleep(1);
}

Verify

Run your binary, then inspect the on-disk queue — events move out of <queue_directory>/pending/ as they upload. Full guide: C / POSIX.

Build firmware with `_honch_core`

The wrapper needs the user C module compiled into your firmware:

make -C ports/unix \
  USER_C_MODULES=/path/to/SDK/ports/micropython/usermod/honch/micropython.cmake

Configure the client

import honch

client = honch.Honch(
    api_key="your-project-key",
    endpoint_url="https://i.honch.io",
    device_id="dev-board-001",
    device_model="dev-board",
    firmware_version="1.0.0",
    event_buffer=bytearray(8192),
)

Send your first event

client.track("app_started")
client.flush()

Keep events flowing

while True:
    client.tick()
    time.sleep(1)

Verify

Watch your capture service receive a POST /capture. Full guide: MicroPython.

Add the library

In platformio.ini:

lib_deps = honch/Honch@^0.3.0

Configure Honch

Connect Wi-Fi first, then construct the config empty and assign fields (do not use designated initializers).

#include <Honch.h>
static uint8_t buf[8192];

HonchConfig config = {};
config.apiKey = "your-project-key";
config.host = "https://i.honch.io";
config.deviceModel = "demo-board";
config.firmwareVersion = "1.0.0";
config.rootCaPem = ROOT_CA_PEM;
config.eventBuffer = buf;
config.eventBufferSize = sizeof(buf);

honch::defaultClient().begin(config);

Send your first event

honch::defaultClient().track("app_started");

Keep events flowing

Pump tick() from your loop or a dedicated task:

void loop() {
  honch::defaultClient().tick();
  delay(1000);
}

Verify

Flash and open the serial monitor; confirm a POST /capture after Wi-Fi connects. Full guide: Arduino.

Send a JSON batch

POST plain JSON to the same endpoint with your project key:

curl -X POST https://i.honch.io/capture \
  -H "Content-Type: application/json" \
  -H "X-Honch-Project-Key: your-project-key" \
  -d '{
    "context": {
      "distinct_id": "device-1",
      "$device_id": "device-1",
      "$device_model": "demo-board",
      "$firmware_version": "1.0.0",
      "$sdk_platform": "custom",
      "$sdk_version": "1.0.0"
    },
    "events": [{ "event": "app_started" }]
  }'

Check	What you should see
Init succeeds	The SDK returns success and queues `$device_boot`.
Flush attempts upload	A `POST /capture` goes out once connected.
Capture accepts	`204` (batch accepted) or `202` (chunk stored). JSON returns `200` with `accepted`.
Event appears	`app_started` shows up in your project's live events.

If events queue but never upload, work through Troubleshooting.

Add A Few Product Events

Once one event is verified, instrument the moments that matter — keep event names stable and put the variable detail in properties:

Event	When
`app_started`	Firmware finished boot and is ready.
`mode_changed`	The device switched modes (property `mode`).
`sync_started` / `sync_finished`	A sync began/ended (property `duration_ms`).
`button_pressed`	A physical input fired (property `pin` or `button`).

Then read Shared Concepts to understand identity, sessions, and how queueing and retries behave.

Quickstart

Set Your Capture Values

Build Your Integration

Install the component

Configure and initialize

Send your first event

Keep events flowing

Verify

Build the SDK

Configure a client

Send your first event

Keep events flowing

Verify

Build firmware with `_honch_core`

Configure the client

Send your first event

Keep events flowing

Verify

Add the library

Configure Honch

Send your first event

Keep events flowing

Verify

Send a JSON batch

Read the response

Validate before launch

Confirm The First Event

Add A Few Product Events