doc · 001thetossproject.com
an OS for yout agent

The Toss Project

Giving AI agents real-world awareness and the ability to act.

est. mmxxvi
mesh · live
node-1 · 4 peers · 7 drivers
fig. 01
cutaway
01 — Plug-and-play drivers

Plug a sensor in. It just works.

Bus scanner sweeps I²C, 1-Wire, and UART every 30s. Unknown chip? TOSS fetches a signed driver descriptor from the online registry, verifies its ed25519 signature, and caches it forever in on-chip SPIFFS.

No firmware rebuild. No re-flash.

bus_scanner active
i2c · 1-wire · uart
5 peripherals · 5 streams
all signed · all cached
sensor
bmp280
Bosch BMP280
I²C 0x76pressure · temp
sensor
sht31
Sensirion SHT31
I²C 0x44humidity · temp
sensor
mpu6050
InvenSense MPU6050
I²C 0x68accel · gyro
display
ssd1306
SSD1306
I²C 0x3C128×64 OLED
sensor
ds18b20
Dallas DS18B20
1-Wiretemperature
actuator
relay_4ch
Generic
GPIOswitch · 4 ch
02 — Mesh networking

Every-one knows each other.

ESP-NOW radio. Peer-to-peer.

Up to 16 neighbors per node.

the entire frame fits in a single 250-byte ESP-NOW packet.

TWP v2 // ESP-NOW
origin-dedup · ttl=3 · crc-16
heartbeat
capability
command
header
26 bytes
  • src_mac6 B
  • dst_mac6 B
  • origin_mac6 B
  • seq2 B
  • type/flag/ttl/len4 B
  • crc-162 B
payload
≤ 224 bytes
  • heartbeatrssi · uptime
  • capabilityname · type · id
  • commanddrv_id · op
  • stream_data16 + 208 B
  • ackseq window
  • authed25519
dedup ring
32 entries
  • origin_machash key
  • seq windowuint16_t
  • ttl decrementon relay
  • broadcastff:ff:ff:ff:ff:ff
  • unicast ack8-frame window
  • heartbeatevery 3 s
03 — Streaming

Sensor to the cloud, in under 5 ms.

Each TWP frame carries up to 52 samples. The gateway fans out to UDP, MQTT, and HTTP in parallel — HTTP runs on a dedicated low-priority task so the mesh RX hot path never blocks.

BMP280I²C read · 4 B/sampleNode Astream_tx_task · ring bufNode Bttl-1 · origin dedupGatewaywifi sta · mcpOutudp · mqtt · http
samples0/s
frames sent0/s
dropped0/s
ack rtt0.00ms
UDP
udp://10.0.0.42:9000
latency
0.5 ms
delivery
fire & forget
MQTT
mqtt://broker.local/toss/sensors
latency
1–3 ms
delivery
QoS 0 / 1 / 2
HTTP
https://api.example.com/ingest
latency
50–500 ms
delivery
POST · queued
04 — LLM-ready

Hand any LLM a USB cable. That's the SDK.

TOSS speaks two languages: a UART shell and an MCP server. Claude, GPT, Ollama — anything that talks JSON-RPC or types into a serial port — drives the entire mesh as one device.

mcp client
LLM · agent
UART · 115200
toss> · node-1
How to Install?

One script. One cable.

Auto-detects your board (ESP32 / S3 / C3), writes the partition table, flashes the firmware, opens the shell. No toolchain. Just Python 3 and USB.

install · zsh
$wget https://github.com/opentoss-io/toss/releases/latest/download/toss-installer.sh
$chmod +x toss-installer.sh && ./toss-installer.sh
• detect board ……… esp32-s3 · /dev/cu.usbmodem01
• erase flash ……… ok (4 MB)
• write partitions … nvs · ota · drvcache
• flash firmware … ok (1.2 MB)
• verify ……… ok (sha256)
✓ TOSS v0.1.0 ready
toss>sys_info