ALMA Home Automation

Concept

A modular home automation system, including software for:

• Android client: Remote control and real-time monitoring of home server gadgets.
• Public server: Connects remote Android clients to associated home servers (hubs).
• Home server: Hub for gadget management within a home network.
• Gadgets: Native ALMA software or supported "off-the-shelf" smart home devices.
• Automations: Trigger actions based on local time, timers or states of gadgets.

ALMA Application Layer Protocol

• Communication protocol for the ALMA nodes (AndroidClients, PublicServer, HomeServer, ALMA gadgets).

Encryption

• AndroidClients ↔️ PublicServer ↔️ HomeServers
  • Data transmission: Public network.
  • Symmetric encrypition (AES with CBC) and message authentication (MAC).
  • Unique secret keys are distributed using asymmetric encryption (RSA) at the initialization of each TCP session.
• HomeServer ↔️ Gadgets
  • Data transmission: Private network (LAN).
  • Native ALMA gadgets: XOR encryption with iterating keys.
  • TP-Link smart plugs: XOR encryption with Autokey (keystream) cipher.
  • RF 433 MHz modules: No encryption.

Software Components

AndroidClient

• Android application for remote control and monitoring of gadget states.
• Connects to PublicServer (for remote access to a HomeServer instance).
• Notified when any changes to a gadget state is detected or successfully requested.
• See: Android design and communications.

PublicServer (remotely accessible)

• Service running on public network (e.g. as daemon on a VPS).
• Connects AndroidClients to HomeServers (hubs).
• Verifies user authentication to (strictly) map AndroidClients to correct HomeServer (hub).
• Eliminates the need of port-forwarding HomeServers.
• Client management using thread pool for asynchronous client connections and communications.
• MySQL:
  • Client authentication data.
  • Map AndroidClients to correct HomeServer instance.
  • Log client traffic (for tracking invalid server access attempts).
• config.json
  • Setup-file for PublicServer.

Example of config.json

{
  "public_server": {
    "tcp_port": 8084,
    "thread_pool": 10,
    "debug_mode": false
  },
  "database_clients": {
    "ip": "localhost",
    "port": 3306,
    "database": "XXXXXX",
    "account": "XXXXXX",
    "password": "XXXXXX"
  },
  "database_traffic_logs": {
    "ip": "localhost",
    "port": 3306,
    "database": "XXXXXX",
    "account": "XXXXXX",
    "password": "XXXXXX"
  }
}

See also: ALMA web admin tool.

HomeServer (local hub)

• The key component of the home automation system.
• Service running inside LAN (e.g. as daemon on a Raspberry Pi).
• Connects to PublicServer (via user authentication).
• Handles:
  • Gadget initialization and communication.
  • Periodically polling gadget states and connectivity.
  • Reporting changes in gadget states and connectivity to AndroidClients (via PublicServer).
  • Processing and executing requests from AndroidClients (e.g. alter a gadget state).
  • Scanning automation triggers and executing automation actions.
• config.json
  • Setup-file for HomeServer.

Example of config.json:

{
  "debug_mode": false,
  "public_server_connection": true,
  "hub_alias": "My House",
  "hub_ID": 107,
  "hub_password": "XXXXXXXXXX",
  "public_server_IP": "XXX.XXX.XXX.XXX",
  "public_server_port": 8084
}

See also: Get started with HomeServer.

Gadgets

• Managed by HomeServer.
• Polled at intervals set uniquelly for each gadget.
• Fast response on request to alter gadget state.
• gadgets.json
  • Setup-file for all gadgets in the HomeServer system.
  • Used for adequate communication with, and representation of, each gadget.
  • For easy (non-hard-coded) gadget introduction and management.
  • Note: HomeServer must be restarted for changes in gadgets.jsonto take effect.

Example of gadgets.json:

{
  "alma": [
    {
      "gadget_id": 1,
      "alias": "My Lamp",
      "type": "CONTROL_ONOFF",
      "poll_delay_seconds": 30,
      "enabled": true,
      "IP_address": "192.168.0.12",
      "TCP_port": 8082,
      "request_spec": null
    },
    {
      "gadget_id": 2,
      "alias": "Temperature (C)",
      "type": "SENSOR_VALUE",
      "poll_delay_seconds": 60,
      "enabled": true,
      "IP_address": "192.168.0.13",
      "TCP_port": 8082,
      "request_spec": "temperature"
    }
  ],
  "tp_link": [],
  "rf433MHz": [],
  "plugins": []
}

See extended example of gadgets.json.

Supported gadget architectures

Each gadget architecture conforms to a property in gadgets.json for easy configuration:

• alma
  • Native ALMA gadgets: Obeys to the ALMA Application Layer Protocol for communication.
  • Easily modular to represent resources ranging from hardware devices (e.g. via ESP8266) to software states (e.g. CPU temperature) and web scraping data.
  • Gadget communication via TCP Sockets.
• tp_link
  • TP-Link smart plugs (HS100 & HS110)
  • Gadget communication via TCP Sockets.
• rf433Mz
  • 433MHz receiver devices.
  • Gadget communication via rpi-rf.
• plugins
  • Specific purpose gadgets being run internally by HomeServer.
  • Plugin gadgets include Raspberry Pi GPIO control and Raspberry Pi CPU temperature monitor.

Note: All gadget configurations and introductions are done in gadgets.json.

Supported gadget types

• Each gadget must be configured (gadgets.json) to be of one of the supported gadget types.
• The predefined gadget types ensures adequate control and representation of each gadget.

public enum GadgetType {CONTROL_ONOFF, CONTROL_VALUE, SENSOR_ONOFF, SENSOR_VALUE}

• CONTROL_ONOFF
  • Interactive.
  • Remotely controlled on/off gadgets (toggle).
  • E.g. Lamp.
• CONTROL_VALUE
  • Interactive.
  • Remotely controlled integer value gadgets.
  • E.g. Temperature threshold.
• SENSOR_ONOFF
  • Not interactive.
  • Remotely monitor on/off state of sensor gadget.
  • E.g. Window is closed.
• SENSOR_VALUE
  • Not interactive.
  • Remotely monitor integer state of sensor gadget.
  • E.g. Temperature sensor.

Automations

• Managed by HomeServer.
• Trigger actions based on local time, timers or states of gadgets.
• automations.json
  • Setup-file for all automations in the HomeServer system.
  • Simple creation and management of gadget automations.
  • Note: HomeServer must be restarted for changes in automations.jsonto take effect.

Example of one automation in automations.json:

{
  "name": "My coffee timer",
  "enabled": true,
  "trigger":
  {
    "type": "event",
    "gadget_id": 7,
    "state_condition": "equal_to",
    "state": 1
  },
  "timer":
  {
    "hours": 0,
    "minutes": 30,
    "seconds": 0
  },
  "action": [
    {
      "gadget_id": 7,
      "state": 0
    }
  ]
}

See extended example of automations.json.

Automation-trigger

• Specifies the condition required to trigger automation actions.
• Two trigger types: event and time.

Trigger type: event

• Trigger the automation actions based on the state of a specified gadget in the system.
• state_condition: Must be one of the following: equal_to, greater_than, less_than, greater_or_equal_to, less_or_equal_to.

"trigger":
{
  "type": "event",
  "gadget_id": 7,
  "state_condition": "equal_to",
  "state": 1
}

Trigger type: time

• Trigger the automation actions based on current local time.
• Required format: HH:mm.

"trigger":
{
  "type": "time",
  "time": "17:00"
}

Automation-timer

• Optional delay between the trigger returning true and the action being executed.

"timer":
{
  "hours": 0,
  "minutes": 0,
  "seconds": 0
}

Automation-action

• Specifes the actions to be executed when the trigger condition returns true.
• The list structure allows a single automation to affect multiple target gadgets.

"action": [
  {
    "gadget_id": 11,
    "state": 1
  },
  {
    "gadget_id": 8,
    "state": 35
  },  
]

Notable repository content

Overall

• 📄 ALMA basic conceptual figure
• 📄 ALMA application layer protocol

Home Server (hub)

• 📄 Get started (Home Server setup)
• 📄 Example: gadgets.json
• 📄 Example: automations.json
• 📁 Home Server Application (Deployable)
• 📁 Home Server Application (Java)
  • 📄 Cryptography scheme
  • 📁 Automations
  • 📁 Gadgets
    • 📄 Native ALMA
    • 📄 TP-Link switches (HS100 & HS110)
    • 📄 RF 433 MHz
    • 📁 Plugins
      • 📄 Local Pi CPU temp
      • 📄 Local Pi GPIO
• 📁 JSON files
  • 📄 automations.json (template)
  • 📄 config.json (template)
  • 📄 gadgets.json (template)
• 📁 Native ALMA gadget examples
  • 📄 ESP8266 CONTROL_ONOFF
  • 📄 ESP8266 CONTROL_VALUE
  • 📄 ESP8266 SENSOR_VALUE
  • 📄 Remote Pi CPU temp SENSOR_VALUE
• 📁 Python scripts
  • 📄 Pi GPIO

Android Client

• 📄 Android design and communications
• 📁 Android Client Application (Java)

Public Server

• 📁 Public Server Application (Java)

Related resources

• 📄 ALMA web admin tool

Updates

• 2020-06-17: Support for TP-Link smart plugs HS100 & HS110.
• 2020-06-22: HomeServer periodically poll gadget states rather than maintaining persistant Socket connections to every gadget. This makes it a more light weight system, with less nested threading and simplifies adding support for other gadget architectures (e.g. off-the-shelf devices).
• 2020-06-26: Debug mode for PublicServer and HomeServer. Fatal exceptions are always logged. However, with "debug_mode":true in config.json, the nodes additionally log all messages being sent or received as part of ordinary operations. This is helpful for debugging node communications.
• 2020-06-29: Property request_spec: String/null for native ALMA gadgets in gadgets.json (HomeServer). By specifying the data requested from a gadget; multiple gadget services can be provided from one gadget unit. E.g. one gadget unit may provide both temperature and humidity data.
• 2020-06-29: Support for 433MHz receiver switches.
• 2020-07-06: Automations: Create and manage gadget automations in automations.json (HomeServer).