The "loosely coupled" agents are the whole point of the Homylon architecture. On any hardware with any programming language you can make your own agents. One side of an agent "talks" to the devices it needs to read or control in their own proprietary protocols. The other side "talks" JSON with the Engine over standard Internet protocols.
Sooner or later every household owns something no existing agent knows about. The old alarm panel in the hall cupboard with a serial port nobody has used in years. A weather station on the roof. A heat pump with a little web page on the local network. A sensor you soldered together yourself. For every one of them the answer is the same: write an agent.
Chapter 9 of the manual, Writing your own agents, shows how. This article gives a short summary.
What an agent does. Whatever device it serves an agent has the same four duties.
- Listen. It waits at its own address and port for messages from the Engine.
- Act. It translates each message into whatever its device understands: a web request, a radio signal, a serial command or a pin on a circuit board.
- Report. When something changes it tells the Engine. A sensor that measures, a lamp switched by hand.
- Introduce itself. Optional. It tells the Engine who it is, where it lives and what it looks after.
An agent that does the first three is a quiet agent. You tell the Engine about it with a few define lines in a scene. An agent that also introduces itself is a capable agent and needs no definition at all.
What an agent must know. Very little of the protocol is enough. The agent receives one JSON message per UDP datagram at its own port. It reports changes to the Engine by UDP at port 55051 and announces itself by TCP at port 55050. It compares actions and names without regard to capitals and quietly ignores anything it does not recognise. The Homylon protocol describes every message in full.
Step by step. The chapter builds Mark Jensen's garden agent: a Raspberry Pi in the shed with a fountain light and a thermometer. It starts as a quiet agent and becomes a capable one by adding a single announce function. The complete agent is under a hundred lines of plain Python and half of those are comments. Only two small functions know about the hardware. Replace them with code for a relay, a web page or a serial port and you have an agent for something else. The skeleton stays.
Testing. Build an agent in small steps with the Engine's monitor open next to it. The monitor shows every message the Engine receives from your agent and sends to it. A one-line scene sends your agent a command. A single terminal command sends the Engine a fake sensor reading without writing any code. And when nothing happens it is nine times out of ten an address, a port or a name with different capitals.
Good manners. An agent a household can rely on for years only reports real changes, keeps its own state, survives restarts on both sides, never lets one bad message stop it, logs what it does and stays on the home network unless you deliberately decide otherwise.
Where an agent can live. Anywhere that can reach the home network and run a program. A Raspberry Pi, a small Linux computer in the meter cupboard, a Mac that is on anyway, a container on a home server. Several agents can share one computer, each at its own port. The language does not matter either. The agents that come with Homylon are written in Swift and Python but C on a microcontroller, JavaScript, Go or even a shell script will do.
For example take an old Raspberry Pi 2B and install Python on it. Then with a simple script read out the P1 port of your electricity meter. Send a message to the Engine when the average power consumption over the last minute or so changes. In the Engine a Homylon scene colours a light depending on the power consumption or production. The Power consumption example shows the scene.
Setting up UDP and TCP in Python takes only a few lines. However when you write a more sophisticated agent or tool in Swift you might find it convenient to use the Homylon Network Kit. It does the networking for you so your agent only has to deal with its device.
Read the full chapter in the manual, with the complete garden agent, online or download it.