Skip to content

AntonGrn/home-auto-ALMA

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

388 Commits
android-client
android-client
 
 
home-server
home-server
 
 
public-server
public-server
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 

Repository files navigation

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

Home Server (hub)

Android Client

Public Server

Related resources

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).

About

Full scale home automation system

Topics

home-automation automation remote-control

Resources

Readme
Activity

Stars

6 stars

Watchers

1 watching

Forks

0 forks
Report repository

Languages