I/O Channels

The device offers several I/O channels for communication, each suited for different use cases.

HTTP

A standard, synchronous channel for simple request/response interactions.

• Port: 80
• Type: Synchronous (Request/Response)
• Data Format: Clear Text
• Best For: Simple API commands, scripting, and integration with services that use standard HTTP requests.

HTTP Server-Sent Events (SSE)

Provides a one-way stream of real-time, JSON-serialized events from the device.

• Port: 80
• Type: Asynchronous (Output-only stream)
• Data Format: JSON
• Best For: Web front-ends or services that need to listen for live device events without the overhead of a full WebSocket connection.
• Endpoints:
  • /events (Recommended)
  • /api/HomeAutomation.HomeGenie/Logging/RealTime.EventStream (Deprecated)

WebSocket

A high-performance, bi-directional channel for low-latency, real-time communication.

• Port: 8188
• Type: Asynchronous (Full-duplex)
• Data Format: Clear Text (JSON) and Binary-packed
• Best For: Advanced user interfaces and control systems requiring immediate, two-way interaction with the device.

MQTT

An asynchronous channel based on the publish/subscribe pattern, ideal for IoT integrations. The device includes a built-in broker.

• Port: 8000 (Broker accessible via WebSocket)
• Type: Asynchronous (Publish/Subscribe)
• Data Format: Clear Text
• Best For: Home automation systems, multi-client environments, and scenarios where clients need to subscribe to specific event topics. Each device module and domain exposes its own topic for commands and events.

Serial Port

A direct, wired connection for debugging and initial setup.

• Connection: USB/UART (115200 bauds)
• Type: Synchronous (Command/Response)
• Data Format: Clear Text
• Best For: Initial configuration, debugging, and direct interaction without a network. This channel is unique as it also provides access to a special set of system-level commands, which are detailed in the Device Setup guide.

Modules and API

HomeGenie Mini API is a subset of HomeGenie Server API which makes of it a "minified" instance of HomeGenie Server specifically designed for microcontrollers.

Regardless the channel used to send API commands they will keep the same syntax:

<domain>/<address>/<command>/<option_1>/.../<option_n>

Commands issued via HTTP or Terminal are prefixed with the base url /api/.

Automation module

Domain / Address

HomeAutomation.HomeGenie/Automation

Commands

• Scheduling.Add
• Scheduling.Update
• Scheduling.ModulesUpdate
• Scheduling.Get
• Scheduling.Delete
• Scheduling.Enable
• Scheduling.Disable
• Scheduling.List
• Scheduling.ListOccurrences
• Scheduling.Templates

Config module

Domain / Address

HomeAutomation.HomeGenie/Config

Commands

• Groups.List
• Modules.Get/<domain>/<address>
• Modules.List
• Modules.ParameterGet/<domain>/<address>/<parameter>
• Modules.ParameterSet/<domain>/<address>/<parameter>/<value>
• Modules.StatisticsGet/<domain>/<address>/<parameter>/<page_number>/<items_per_page>
• WebSocket.GetToken
• System.Configure
  • Location.Get
  • Location.Set
  • System.Info
  • System.TimeSet/<epoch_ms>

<GPIO> module

Domain / Address

HomeAutomation.HomeGenie/<module_address>

Commands

• Control.On
• Control.Off
• Control.Level/<level>
• Control.Toggle

Where <module_address> is the GPIO number. So to set HIGH the GPIO5 the API command will be:

  HomeAutomation.HomeGenie/5/Control.On

To configure GPIO modules the following firmware parameters are available:

These parameters allow configuring up to 8 I/O modules.

IO Channel Type (io-typ0*) can be one of the following: 'Switch','Light' or 'Dimmer'.

Example

#SET:io-typ01 Dimmer
#SET:io-pin01 5
#SET:io-typ02 Dimmer
#SET:io-pin02 6

Besides the built-in GPIO modules, you can create custom modules to control more complex hardware. The Smart Light example demonstrates this by defining a C1 module that is mapped to an RGB LED for full color control.

mini module

Builtin sensor module.

Domain / Address

HomeAutomation.HomeGenie/mini

Properties

• System.BytesFree

Example

Getting the mini module by calling the API method Modules.Get of the Config module:

HTTP

http://<hg_mini_ip>/api/HomeAutomation.HomeGenie/Config/Modules.Get/HomeAutomation.HomeGenie/mini

Serial Port

/api/HomeAutomation.HomeGenie/Config/Modules.Get/HomeAutomation.HomeGenie/mini

Response

{
  "Name": "HG-Mini",
  "Description": "HomeGenie Mini node",
  "DeviceType": "Sensor",
  "Domain": "HomeAutomation.HomeGenie",
  "Address": "mini",
  "Properties": [{
    "Name": "Sensor.Luminance",
    "Value": "114",
    "UpdateTime": "2019-01-30T13:34:02.293Z"
  },{
    "Name": "Sensor.Temperature",
    "Value": "18.25",
    "UpdateTime": "2019-01-30T13:34:02.293Z"
  },{
    "Name": "System.BytesFree",
    "Value": "2243167",
    "UpdateTime": "2024-03-13T18:06:08.730Z"
  }]
}