inanimate/resident

Readme

# Resident

Sandbox with hardware IO and hot reload for ESP32 devices.

Resident provides a sandboxed Lua runtime that can be loaded with new code over the network at any time. Hardware peripherals are exposed to Lua through a driver interface, so apps can draw to displays, read sensors, and control outputs without touching C++.

## What Resident includes

1. The Resident firmware library for a sandbox on ESP32 devices and custom hardware integration, with optional managed connectivity to load sandbox apps remotely.
2. A default websocket backend at `resident.inanimate.tech/devices/<deviceId>` to relay apps and events during development.
3. Agent skills to create, validate and push sandbox apps. [Install the Resident skills plug-in](tools/agent-plugin/README.md).

Point your agent at [docs/start-building.md](docs/start-building.md) to add the Resident sandbox to your hardware.

## Examples

Working projects live under [examples/](examples/) — the M5StickC Plus2 (`m5stick-demo`, plus `m5stick-voice` and `m5stick-clock`), the Adafruit ESP32-S2 TFT Feather, and a bare ESP-IDF build (`espidf-basic`). Each is buildable as-is; use them as templates for bringing up your own hardware.

### Quick start

`Resident::Sandbox` composes [Courier](https://github.com/inanimate-tech/courier) for connectivity with the Lua runtime. It handles WiFi, WebSocket transport, and message routing automatically — populate `cfg.network` and the sandbox connects on `setup()`.

```cpp
#include <Resident.h>
#include "MyDisplayDriver.h"
#include "MyButtonDriver.h"

MyDisplayDriver display;
MyButtonDriver button{...};   // however your driver takes config

Resident::SandboxConfig makeConfig() {
    Resident::SandboxConfig cfg;
    cfg.deviceType    = "demo";
    cfg.systemDisplay = &display;
    cfg.extensions    = {&display, &button};

    // Courier::Config has a constructor with default args, so designated
    // initializers (`Courier::Config{ .host = ... }`) don't compile under
    // strict ESP-IDF builds. Use direct field assignment.
    Courier::Config courier;
    courier.host = "resident.inanimate.tech";
    cfg.network  = courier;

    return cfg;
}

Resident::Sandbox sandbox{makeConfig()};

void setup() {
    // Optional: override the default WS path on the canonical relay.
    sandbox.onTransportsWillConnect([]() {
        String path = String("/devices/") + sandbox.getDeviceId();
        sandbox.ws().setEndpoint("resident.inanimate.tech", 443, path.c_str());
    });

    sandbox.setup();
}

void loop() {
    sandbox.loop();
}
```

The device connects to WiFi (via a WiFiManager captive portal), opens a WebSocket to your server, and accepts Lua apps as JSON messages.

> Omit `cfg.network` and the sandbox runs standalone with no WiFi pulled in — `sandbox.loop()` ticks Lua at 10 FPS unconditionally, and `isConnected()` returns `false`.

Register reactive callbacks before `setup()` to react to lifecycle events:

```cpp
sandbox.onConnected([]() {
    // load a bootstrap Lua app once the WS is up
});

sandbox.onMessageWithChannel("system", [](const char* transport, const char* type, JsonDocument& doc) {
    // custom control-plane types; Resident handles the reserved ones itself
});
```

## Writing a Driver

Drivers expose hardware to Lua via a builder API:

```cpp
#include <ResidentDriver.h>
#include <ResidentLuaModule.h>
#include <M5Unified.h>

extern "C" {
  #include "lua/lua.h"
  #include "lua/lauxlib.h"
}

class IMUDriver : public Resident::Driver {
public:
    const char* name() const override { return "imu"; }
    void registerModule(Resident::LuaModule& m) override {
        m.method<IMUDriver, &IMUDriver::accel>("accel");
    }

    int accel(lua_State* L) {
        M5.Imu.update();
        auto d = M5.Imu.getImuData();
        lua_pushnumber(L, d.accel.x);
        lua_pushnumber(L, d.accel.y);
        lua_pushnumber(L, d.accel.z);
        return 3;
    }
};
```

Then in Lua:

```lua
function on_tick(ctx, dt_ms)
    local ax, ay, az = imu.accel()
    -- use acceleration data
end
```

For Lua-only extensions that don't expose hardware or emit events, extend `Resident::Extension` directly instead of `Resident::Driver` — the same `registerModule(LuaModule&)` and lifecycle hooks apply.

### Driver lifecycle

- `begin()` — called once by `Sandbox::setup()` in registration order.
  Hardware init goes here. Idempotent: a manual early call is safe (the
  Sandbox's call becomes a no-op).
- `update()` — called every iteration of `Sandbox::loop()`. Use for
  per-tick driver work like polling and debouncing. Runs at full main-loop
  rate, distinct from Lua's 10 FPS `on_tick`.
- `registerModule(LuaModule& m)` — called once by `Sandbox::setup()`
  to register the driver's Lua-visible global. Use the builder's
  `method<>`, `staticMethod`, and `constant` overloads.
- `onAppReset()` — called when a new app is loaded (before compilation).
- `onAppRunning(bool)` — called when an app starts or stops running.

## Message Protocol

Every message carries an envelope `channel` field that steers it onto a plane:

```json
{ "channel": "system", "type": "app",   "code": "function on_tick(ctx, dt_ms) ... end" }
{ "channel": "app",    "type": "button_press", "data": { "id": 1 } }
```

`channel:"app"` is the data plane — it reaches the Lua `on_event`. `channel:"system"` is the control plane, where Resident handles the reserved types (`app`, `chunk`, `forget`, `framework`, `hello`, `goodbye`) itself and hands anything else to a slot registered with `onMessageWithChannel("system", cb)`. Any other channel name gets its own slot. See [docs/api.md](docs/api.md#channel-routing) for the full picture, including the un-channelled legacy path.

### Sandbox lifecycle

- `init(ctx)` — called once after compilation
- `on_tick(ctx, dt_ms)` — called at 10 FPS with elapsed time
- `on_event(ctx, event)` — called for wire events and driver events, with the payload in `event.data`

The `ctx` table contains: `time_ms` (milliseconds since the app loaded) and `generation_id` (when the load message carried one).

### Time

The Lua `datetime` module is Python's `datetime` — `datetime.now()`, `datetime.date(...)`, `datetime.timedelta{...}`, arithmetic and comparisons between them, `strftime` — in whole seconds, because the Lua is built with 32-bit numbers. Every datetime is local (the zone `setTimezone` resolved, DST applied) or `datetime.UTC`. `datetime.synced()` says whether the wall clock has been set. See [docs/api.md](docs/api.md#datetime-module).

```lua
if datetime.synced() then
    local now = datetime.now()                 -- local once a timezone is set
    log.info(now:strftime("%a %H:%M"))         -- "Mon 13:05"
    local is_weekend = now:weekday() >= 5      -- Monday = 0
    local days_left = (datetime.date(2026, 12, 25) - datetime.today()).days
end
```

Elapsed time is the `time` module's MicroPython ticks, `time.ticks_ms()` / `time.ticks_diff()`. Its calendar half (`time.localtime()`, `time.strftime()`, …) is deprecated for `datetime`: it still works, and warns once per app load.

### Timezone

`Sandbox::setTimezone(const char* ianaZone)` — set the sandbox's local timezone for `datetime` (and the deprecated `time.localtime()`). Pass an IANA zone string (e.g. `"Europe/London"`). ezTime performs a UDP lookup to `timezoned.rop.nl` on first sight of a zone and caches the POSIX string in EEPROM. On failure (null / empty / unrecognised zone), the sandbox falls back to UTC.

`Sandbox::hasTimezone() const` — returns `true` after a successful `setTimezone`. Until then, local time is UTC (`datetime.now():tzname()` reads `"UTC"`).

## Building

### PlatformIO

```ini
[env:dev]
platform = espressif32@6.12.0
board = esp32-s3-devkitc-1
framework = arduino
lib_deps =
    https://github.com/inanimate-tech/resident.git
    https://github.com/inanimate-tech/courier.git
    tzapu/WiFiManager@^2.0.17
    bblanchon/ArduinoJson@^7.4.2
    ropg/ezTime@^0.8.3
    fischer-simon/Esp32Lua@^5.4.7
```

### ESP-IDF (Arduino as component)

Add to your `CMakeLists.txt`:

```cmake
set(EXTRA_COMPONENT_DIRS ../vendor)
```

And in `idf_component.yml`:

```yaml
dependencies:
  inanimate/resident:
    version: "^0.7.0"
```

## License

[MIT](LICENSE)