The Homylon protocol is the machine-facing door of the Engine. Agents, remotes, monitors and notification programs use it to exchange short JSON messages. The protocol is intentionally made from ordinary network technology: JSON, UDP, TCP, addresses and ports. Any language or platform that can send JSON can join the house.

One JSON object per message

Every message has an action and named values. Action spelling is forgiving: capitals, hyphens and underscores do not change its meaning. Names are compared in lower case. Unknown fields are ignored by the Engine, which leaves room for device-specific options to pass through.

{"action":"ChangeLightState","identifier":"porchlight","onOff":"on","brightness":"100"}

Most messages are small and travel over UDP. A UDP datagram contains exactly one UTF-8 JSON message and is kept below 1,000 bytes. TCP is used for larger lists and announcements. Each TCP connection carries one message: a four-byte, most-significant-byte-first length followed by that many bytes of JSON, then the connection closes.

Default network doors

The Engine normally listens on UDP port 55051 and TCP port 55050. Agents announce the address and port where they can receive commands. Programs may use the same number for both transports if desired. Homylon also uses ordinary network discovery so mature agents can find the Engine and introduce themselves.

Message families

• Commands to agents: ChangeLightState, open, close, ChangeApplianceState, ChangeMediaState, play, stop, pause, resume, record, route and requestannouncement.
• Events from agents: registeragent, changedsensor, changedlight, changedblind, changedremote and changedvariable.
• Remotes: register, request device and scene lists, change lights/groups/blinds, and receive updates when anything changes.
• Monitors: register for event, engine, error, warning, log, notification or protocol traffic.
• Notifications: go to a notification, email, SMS or message agent chosen by the owner.

Example agent exchange

{"action":"registeragent","announcement":{
  "announce":{"agent":"gardenpi","type":"sensors","ipaddress":"192.168.1.60",
    "ports":[{"networkProtocol":"udp","port":55300}]},
  "list":[{"name":"gardenthermometer","type":"temperature","state":{"temperature":12.5}}]
}}

{"action":"changedsensor","name":"gardenthermometer","type":"temperature","status":12.5}

The Engine sends a request for announcements when a package opens and about once a minute. Repeating an announcement is safe: the Engine updates what it knows instead of adding duplicates, while definitions written by the user are never overwritten.

Keep the protocol local

The protocol is open by design, so a program on the home network can participate without an account or certificate. That also means the Engine's ports should not be exposed directly to the internet. Use firewall rules and a VPN for remote access. If a message is meant to leave the house, send it through an agent so the owner can choose exactly which service receives it.

Based on the Homylon User Manual - Draft, chapters 2 and 8 and appendix B.