Homylon protocol cheatsheet

A compact reference for programs that talk to the Homylon Engine. Messages are UTF-8 JSON objects with an action field.

Transport

UDP: one JSON object per datagram; the Engine's default port is 55051; keep messages below 1,000 bytes.
TCP: one message per connection; default port 55050; send a four-byte big-endian length followed by the JSON bytes, then close.
UDP is the normal choice for commands, events and heartbeats. TCP is used for lists, announcements and other larger messages.
The same content means the same thing regardless of transport.

Rules for JSON

{"action":"ChangeLightState","identifier":"readinglamp","onOff":"on","brightness":"60","color":"ffd8a0","fade":"3"}

Action spelling is forgiving: case, hyphens and underscores do not matter.
Names are compared in lower case.
Unknown fields are ignored and may be passed through as device-specific details.
Use strings for protocol values unless the message definition calls for a JSON number, boolean or array.

Commands to agents

{"action":"ChangeLightState","identifier":"lamp","onOff":"on","brightness":"80"}
{"action":"open","type":"curtain","identifier":"livingcurtains","percentage":"70"}
{"action":"close","type":"door","identifier":"frontdoor"}
{"action":"ChangeApplianceState","appliance":"terraceheater","state":"on"}
{"action":"play","identifier":"livingspeakers","type":"speaker","content":"playlist","media":["sundaymorning"],"volume":"20"}
{"action":"route","identifier":"gatecamera","type":"camera","to":["livingtv"]}
{"action":"requestannouncement"}

Light messages always carry action and identifier. Optional fields include onOff, brightness, color, temperature, fade and blink. A remote request may add requestID; the agent returns it in changedlight.

Agent registration and events

{"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}
{"action":"changedlight","name":"fountainlight","state":"on","brightness":60,"requestID":"..."}
{"action":"changedblind","name":"kitchenblind","percentage":40}
{"action":"changedremote","remote":"gardenpanel","control":"fountain","value":"clicked"}
{"action":"changedvariable","variable":"rain","value":1}

Send registeragent over TCP because the list can be long. Repeating it updates the Engine safely. The announcement describes the agent and its ports; the list describes lights, sensors, blinds, appliances or groups.

Remotes

{"action":"registerremote","remote":{"name":"emmasphone","address":"192.168.1.31","port":55250,"protocol":"tcp","session":"3F2A..."}}
{"action":"requestlights","remote":"emmasphone"}
{"action":"setlight","identifier":"readinglamp","onOff":"on","brightness":40,"requestID":"..."}
{"action":"setgroup","identifier":"livingroom","onOff":"off"}
{"action":"setblind","identifier":"kitchenblind","percentage":30}

A remote registers at startup and repeats its heartbeat about every three seconds. It receives complete lists over TCP and live updates such as lightchanged, sensorchanged, groupchanged and blindchanged over UDP.

Monitors and people

{"action":"registermonitor","monitor":{"name":"emmaipad","address":"192.168.1.30","port":55213,"protocol":"udp","types":"all, heart","heartbeat":3}}

{"monitorMessageText":"Sensor FRONTDOORSENSOR changed to 1","monitorMessageTime":780451200.5,"monitorMessageType":"Event"}

{"message":"Someone is at the front door","user":"mark","title":"Homylon","urgent":true}

Notifications, email and text are handed to agents chosen by the owner. They are the only part that needs to leave the home network.

Security reminder

The protocol assumes a trusted home network. Do not expose ports 55050 or 55051 directly to the internet. Use local firewall rules and a VPN for remote access.

Main Menu