Audience
For developers
Arvio's driver format and protocol, as they run on the hub. To write a driver, talk to SFK.
On this page
A driver is a small program that connects a brand or a protocol to Arvio. The format and protocol you see here are the ones running on hubs.
What a driver looks like
A folder with an arvio-driver.json file and an entry file. Arvio Core starts it as a process, in Node or Python, and they talk in lines of JSON over stdin and stdout.
Arvio Core holds the devices, rooms, commands and automations. A driver only knows how to talk to its device: it declares what exists, sends states and carries out commands.
The arvio-driver.json file
| Field | Example | What it means |
|---|---|---|
| id | systems.arvio.hue | A unique dotted name. It cannot start with core. |
| version | 0.1.0 | A version of the form x.y.z. |
| runtime | node | node or python. |
| entry | driver.ts | The entry file, inside the driver's folder. |
| name | Philips Hue | The name for people. |
| permissions | net:lan | A list from radio:zigbee, radio:zwave, radio:ble, net:lan, net:cloud, danger:lock, danger:alarm, danger:gate. |
| license | UNLICENSED | MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, or UNLICENSED for SFK's own code. |
| memory_mb | 48 | A memory cap for Node drivers, from 16 to 1024. The default is 96. |
| isolation | shared | process, the default, or shared, a common process for reviewed SFK Node drivers only. |
The protocol
One line of JSON per message.
| Direction | Message | What it says |
|---|---|---|
| driver → core | {"type":"ready"} | The driver has started. |
| driver → core | {"type":"entity", native_id, domain, name, object_id?} | Declares a device. |
| driver → core | {"type":"state", native_id, state, attributes?} | A new state. |
| driver → core | {"type":"ack", id, ok, error?} | The result of a command. |
| driver → core | {"type":"event", native_id?, event, data?} | An event, such as a button press. |
| driver → core | {"type":"log", level, msg} | A log line. |
| core → driver | {"type":"command", id, native_id, domain, service, data} | A command for a device. |
| core → driver | {"type":"setup", id, action, data} | A setup action, such as adding a device with its keys. The driver answers with setup_reply. |
The rules for a driver
- A driver exits when its stdin closes, so it never holds a port if Arvio Core stops.
- If it crashes, it restarts with a delay of 1 to 60 seconds. More than 5 crashes in 10 minutes disable it. Arvio Core stays up.
- A driver with an invalid manifest does not start, and Arvio Core logs it.
- A driver does not get Arvio Core's environment or secrets, only the minimum and its own data folder.
- Lines over 64 KB are ignored.
- Locks, alarms and gates are never actuated at start-up. Dangerous commands need a confirmation, or Arvio Core rejects them.
Common questions
What language is a driver written in?
Node or Python. SFK's drivers are in TypeScript. The protocol is lines of JSON, so it does not depend on a library of ours.
Can I download a driver as an example?
No. The marketplace gives out no code. The format and the protocol are on this page.
Want to write a driver?
Tell us for which brand or protocol.
Tell us about your space
Tell us what you have and what you want, and we will work out together what your space needs.
