Getting Started Skill

Build embedded IoT applications using the Ioto Device Agent SDK. This skill guides you through app scaffolding, templates, integration models, and the fiber execution model.

Invoke with: /getting-started

Prerequisites

• GCC or compatible C compiler
• Make (GNU Make)
• OpenSSL or MbedTLS for TLS support
• TestMe (tm) for unit tests: npm install -g testme
• Vite for building a UI: npm install -g vite

App Directory Layout

A user's app lives in its own directory with the Ioto agent installed as a subdirectory:

myapp/
├── src/                    # Your application source code
├── Makefile                # Your build file
├── ioto/                   # Extracted Ioto source distribution
│   ├── include/            # Ioto headers (ioto.h and dependencies)
│   ├── build/
│   │   └── bin/            # Built library and tools
│   │       └── libioto.a   # Static library (Linux/macOS)
│   └── ...
└── state/
    └── config/             # Runtime configuration files
        ├── ioto.json5      # Main Ioto configuration
        ├── device.json5    # Device identification
        └── web.json5       # Web server config (if web enabled)

Sample Apps

The Ioto agent source distribution includes sample apps under ioto/apps/ that provide working configuration and source code for common use cases:

App	Use Case	Includes
blank	Minimal skeleton	Just ioStart()/ioStop(), no services
http	Web server with auth	HTTP/HTTPS, database, REST APIs, user/admin roles
ai	AI-enabled device	OpenAI integration, streaming, agentic workflows
blink	ESP32 demo	Minimal example for microcontroller targeting
unit	Test harness	Comprehensive unit test execution framework

Creating a New App

1. Create the app directory and install the Ioto agent:

mkdir myapp && cd myapp
tar xf ioto-VERSION.tar.gz && mv ioto-* ioto

2. Copy configuration from a sample app:

mkdir -p src state/config
cp ioto/apps/http/*.json5 state/config/

3. Configure services in ioto/include/config.h and rebuild with make -C ioto clean && make -C ioto.

4. Create src/myapp.c with entry points and a Makefile.

Integration Models

Own Main (Full Control)

#include "ioto.h"

int main()
{
    ioStartRuntime(1);
    ioRun(NULL);
    ioStopRuntime();
    return 0;
}

int ioStart(void)
{
    rInfo("app", "Hello World");
    return 0;
}

void ioStop(void) {}

Ioto-Managed Main (Simpler)

#include "ioto.h"

PUBLIC int ioStart(void)
{
    rInfo("app", "Hello World");
    return 0;
}

PUBLIC void ioStop(void) {}

Building and Running

make -C ioto              # Build libioto.a
cc -c -I ioto/include src/myapp.c
cc -o myapp myapp.o ioto/build/bin/libioto.a -lssl -lcrypto
./myapp

Configuring Services

Services are controlled at two levels:

1. Compile-time — Edit ioto/include/config.h (SERVICES_* defines).
2. Runtime — Edit state/config/ioto.json5 (services property).

{
    services: {
        database: true,
        web: true,
        url: true,
    },
    limits: { fiberStack: '64k' },
}

Fiber Model

Ioto uses single-threaded cooperative fiber scheduling:

• All code runs in fibers — never block in a tight loop
• Use fiber-aware I/O: rSleep(), webRead(), urlFetch(), mqttPublish()
• Configure stack size via limits.fiberStack in ioto.json5
• Avoid large stack allocations (>4KB); use rAlloc() for heap instead