Want Arvio in your space? Tell us what you have and what you want. Talk to us ›

Language: Eng
Partner sign-in
Arvio
Contact

Audience

For developers

Arvio's driver format and protocol, as they run on the hub. To write a driver, talk to SFK.

Talk to us

On this page
  1. What a driver looks like
  2. The arvio-driver.json file
  3. The protocol
  4. The rules for a driver
  5. Common questions

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

FieldExampleWhat it means
idsystems.arvio.hueA unique dotted name. It cannot start with core.
version0.1.0A version of the form x.y.z.
runtimenodenode or python.
entrydriver.tsThe entry file, inside the driver's folder.
namePhilips HueThe name for people.
permissionsnet:lanA list from radio:zigbee, radio:zwave, radio:ble, net:lan, net:cloud, danger:lock, danger:alarm, danger:gate.
licenseUNLICENSEDMIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, or UNLICENSED for SFK's own code.
memory_mb48A memory cap for Node drivers, from 16 to 1024. The default is 96.
isolationsharedprocess, the default, or shared, a common process for reviewed SFK Node drivers only.

The protocol

One line of JSON per message.

DirectionMessageWhat 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.