KB: module types explained
This article expands on the module overview document.
Module types are simply labels attached a module to give the user an idea of the primary purpose of a module. In reality, modules may perform more than one of of the functions listed below.
- Command Modules - Process a specific device type or a family of devices. For example: X10 Lamps and Appliance Modules, Audio/Video Receivers. Command modules typically process commands at a high level, and format commands to be handle by various interface modules. Command modules can be thought of as providing an extended API for a product type or family.
- Interface Modules - Acts as the transport layer between the device and the command module. For example, a CM11a interface module talks to CM11a devices and translates it into a standard format that the X10API command module can handle. While another interface module can talk a network based controller, but still present commands to the X10API command module the same way.
- Logic Modules - A module that provides logic. It can receive status updates and request actions. Such as "If garage door is open, turn on the master bedroom table lamp". Or "If front door bell rings, request the front door camera to take a picture".
- Other - Anything else that doesn't fit in the above.
Command modules should implement hooks for device types that it can process commands for. It is responsible for processing the command and making a common format that interface modules can process the command easier. Lets use an Insteon command module for this section as an example. An insteon command module should be named "InsteonAPI". It implements a hook to receive commands for any insteon device types. InsteonAPI will take that command and format it in such a way that any Insteon Interface module can understand. For example, it will convert a cmd_id to a "command" (such as 18 = ON). It will also lookup the device_id and get the address, such as as "8d.3a.93". It may do other things, but eventually it will wrap this all up into a dictionary to be handed of to any Inteon Interface the user has designated (such as a network, USB, or Serial module connected to the computer). Going the other direction, the InsteonAPI will be able to receive dictionaries of data outlining the device address and a new status from an interface module. The InsteonAPI module will then generate a new Yombo status message to broadcast to the rest of the gateway software so that other modules and components will know about it. Refer to [Product Family Standards] article for details about specific information contained in the dictionaries as they vary from one product family to another. There should be no logic in the command module, other than correctly generating messages to a support interface module and to the gateway software.
Interface modules are responsible for receiving dictionaries of information from their command module and converting it a format the receiving device can handle. Think of the interface module as the transport layer. It's the final leg between the gateway software and the actual device. The transport layer can be any method you can think of: email, IM, SMS, serial port, usb port... There should be no logic in the interface module, other than correctly generating messages to a command interface module and to the end device.
These are the brains of the gateway. They are responsible for monitoring status messages for changes in device state can send out command messages to alter device states. An example is a garage door monitoring module. It would listen for garage door states (open or closed) and send out various commands. An example of this would be that when the garage door opens, it sends a command to display a warning on a tv, send an SMS, turn on a garage light. It can than track how long the garage door is and close it automatically after a set amount of time. If there is a motion detector in the garage, it can monitor that and reset the auto close timer. Due to the highly variable nature of devices connected to a gateway, the majority of logic modules will be generated by end users. If end users want to share their logic modules with other end users, it's highly suggested that they use github.com for code sharing.