Fork me on GitHub

pimatic-radiohead by Peter Müller (crycode) | github | npm

build status npm version

pimatic-radiohead

pimatic-radiohead is a pimatic plugin that integrates RadioHead into pimatic.

With pimatic-radiohead you are able to include pimatic into your RadioHead network using a serial interface. You may also use a small microprocessor (e.g. an Arduino nano) as a serial-radio-gateway to include some radio hardware.

Build you own bus system based on pimatic, RS485 and radio devices!

RadioHead is a open source Packet Radio library for embedded microprocessors. It provides addressed, reliable, retransmitted, acknowledged variable length messages.

pimatic-radiohead uses the radiohead-serial Node.js module.

German version of this readme: README-de.md

Features

  • Receive messages/commands from other nodes in you local RadioHead network.
  • Send messages/commands to other nodes in you local RadioHead network.
  • Devices to show and process messages received from other nodes.
  • Devices to send messages to other nodes.
  • Rules are supported for triggering actions and sending messages including variables.
  • Device attributes give you some statistics about sent and received messages.
  • Multiple RadioHead networks are supported using different serial interfaces.

Device configuration localized in:

  • en - English
  • de - German

Devices

All device configuration can be done using the pimatic frontend.

A detailed description of all config options is available in the file device-config-schema.coffee.

RadioHeadSerialPort

This is a special device, which provides the interface to the serial hardware.

It is needed for all other devices.

By default only messages addressed to this node or the broadcast address are handled. You may activate the promiscuous mode to handle messages with any to address.

RadioHeadSerialPort

RadioHeadContactSensor

A ContactSensor based on received messages.

You need to define some data bytes, which have to match a received messages for the closed and opened action. An automatic reset is also possible, if the sending device only emits one action.

RadioHeadContactSensor

RadioHeadPresenceSensor

A PresenceSensor based on received messages.

You need to define some data bytes, which have to match a received messages for the present and absent action. An automatic reset is also possible, if the sending device only emits one action.

RadioHeadPresenceSensor

RadioHeadSwitch

A Switch which sends configurable messages if turned on or off.

RadioHeadSwitch

RadioHeadShutter

A ShutterController which sends configurable messages if moved up, moved down or stopped. An automatic stop is also possible, if you wish to stop after a specific time.

RadioHeadShutter

RadioHeadButtonsDevice

A ButtonsDevice to provide some buttons. One button can send and/or receive messages.

You may use this device to send a message if the user clicks a button in the frontend.

You may also use this device to handle some buttons from a remote control.

RadioHeadButtonsDevice

RadioHeadButtonsDevice

RadioHeadButtonsDevice

RadioHeadWeatherStation

A Sensor which can receive and display various weather information.

You are able to define multiple data messages to extract the values. Each value can be preprocessed by an expression to manipulate the received value.

Values which consists of more than one byte can be in Little-Endian (LE) or Big-Endian (BE) format.

Supported data types in a message are: 32bit Float LE, 64bit Double LE, 8bit Integer, 8bit Unsigned Integer, 16bit Integer LE, 16bit Unsigned Integer LE, 32bit Integer LE, 32bit Unsigned Integer LE, 4bit Float BE, 8bit Double BE, 16bit Integer BE, 16bit Unsigned Integer BE, 32bit Integer BE, 32bit Unsigned Integer BE

Use the following indicators to mark the positions of the values in the data messages:

  • t - temperature
  • h - humidity
  • r - rain
  • ws - wind speed
  • wd - wind direction
  • wg - wind gust
  • b - battery status
  • lb - low battery

RadioHeadWeatherStation

RadioHeadWeatherStation

RadioHeadCustomSensor

A Sensor which can receive and display various numeric and boolean data.

You can define multiple custom numeric and boolean sensor values and you are able to define multiple data messages to extract the values. Each numeric value can be preprocessed by an expression to manipulate the received value.

Values which consists of more than one byte can be in Little-Endian (LE) or Big-Endian (BE) format.

Supported data types in a message are: 32bit Float LE, 64bit Double LE, 8bit Integer, 8bit Unsigned Integer, 16bit Integer LE, 16bit Unsigned Integer LE, 32bit Integer LE, 32bit Unsigned Integer LE, 4bit Float BE, 8bit Double BE, 16bit Integer BE, 16bit Unsigned Integer BE, 32bit Integer BE, 32bit Unsigned Integer BE

Use you own or the following predefined indicators to mark the positions of the values in the data messages:

  • b - battery status

RadioHeadCustomSensor

RadioHeadCustomSensor

RadioHeadCustomSensor

RadioHeadCustomSensor

Rule syntax and examples

Predicates (when ...)

You may use the following conditionals to trigger a rule:

radiohead [received] "<dataBytes>" from <senderAddress> [to <recipientAddress>] using <device>
  • received - Optional word for better readability.
  • dataBytes - The received data bytes in hex notation, separated by spaces. You may use a * as wildcard to accept any byte at this position.
  • senderAddress - The address of the sending node in the RadioHead network in hex notation. You may use 0xFF to accept all senders.
  • recipientAddress - Optional. The address of the receiving node in the RadioHead network in hex notation. If omitted, the own address of the device will be used. Useful for broadcasts or if the RadioHeadSerialPort device is used in promiscuous mode.
  • device - ID or name of the RadioHeadSerialPort device which is used.

Examples

radiohead received "0x01 0x02 0xAB" from 0x05 using rh-serial-1

radiohead received "0x01 0x02 0xAB" from 0x05 to 0x01 using rh-serial-1

radiohead "0x63 0x72 0x79 0x43 0x6F 0x64 0x65 * 0x64 0x65" from 0xFF using rh-serial-1

rule-when

Actions (then ...)

You may use the following action in a rule:

[send] radiohead "<dataBytes>" to <recipientAddress> using <device>
  • send - Optional word for better readability.
  • dataBytes - The data bytes in hex notation to send, separated by spaces. You may also use variables as described below.
  • recipientAddress - The address of the receiving node in the RadioHead network in hex notation. Use 0xFF for broadcast messages.
  • device - ID or name of the RadioHeadSerialPort device which is used.

Examples

send radiohead "0x01 0x02 0xAB" to 0x05 using rh-serial-1

radiohead "0x63 0x72 0x79 0x43 0x6F 0x64 0x65" to 0xFF using rh-serial-1

send radiohead "0x55 $my_var d$my_double_var i$my_int_var b$my_boolean_var" to 0x42 using rh-serial-1

rule-then

rule-when-then

Variables in Actions

You can include pimatic variables in the data bytes as well as static byte values.

There are some modifiers to define the datatype of the transmitted variable content. A modifier is a single letter, which is prefixed to the variable name.

  • Without any modifier a variable will be sent as one byte, representing the 8-bit unsigned integer value of that variable.
  • i - 32-bit integer
  • I - 16-bit unsigned integer
  • d - 64-bit double
  • f - 32-bit float
  • b - boolean (false=0x00, true=0x01)

All variables will be sent using little-endian format.

Example

"0x01 $my_var d$my_temperature" will sent 10 bytes: One byte with the fixed value 0x01, one byte representing the 8-bit value of $my_var and 8 bytes representing the temperature saved as double in $my_temperature.

Attributes

The following attributes are provided by each RadioHeadSerialPort device as pimatic variables:

  • sentOkCount - The count of successfully sent messages since the last start.
  • sentErrorCount - The count of faulty sent messages since the last start.
  • receivedCount - The count of received messages since the last start.
  • retransmissionsCount - The count of retransmitted messages since the last start. High values indecat problems (e.g. bus collisions or unreachable devices).

Debug

You can enable the debug mode in the plugin config.

In debug mode you will find all received RadioHead messages in the log and some other additional information, e.g. about matched data for the devices.

License

Licensed under GPL Version 2

Copyright (c) 2017 Peter Müller peter@crycode.de (https://crycode.de/)

Some parts of the RadioHeadWeatherStation devices are inspired by pimatic-homeduino.

Plugin Config Options

RadioHead config options
OptionDescriptionDefault
debug
boolean
Enable debug output
false

Device Config Options

RadioHead device config schemes

RadioHeadSerialPort

RadioHeadSerialPort config options
OptionDescriptionDefault
port
string
The serial port used for the communication.
"/dev/ttyUSB0"
baud
integer
The baud rate used for the communication.
9600
address
string
The address of this node in the RadioHead network in hex or dec. (0x00 to 0xFE)
"0x01"
promiscuous
boolean
Tells the receiver to accept messages with any to address, not just messages addressed to this node or the broadcast address.
false
reliable
boolean
Use the manager 'RHReliableDatagram' (true) or 'RHDatagram' (false).
true
retries
number
The maximum number of retries for sending a message. If set to 0, each message will only ever be sent once.
3
timeout
number
The minimum retransmit timeout in milliseconds. If an ack is taking longer than this time, a message will be retransmitted.
200

RadioHeadContactSensor

RadioHeadContactSensor config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress
string
The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress
string
The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.
""
dataClosed
array of strings
Array with the data bytes of the message in hex or dec for the 'closed' action. Use * to ignore specific data bytes.
[]
dataOpened
array of strings
Array with the data bytes of the message in hex or dec for the 'opened' action. Use * to ignore specific data bytes.
[]
autoReset
boolean
Reset the state after resetTime. Useful for contact sensors, that only emit open or close events.
false
resetTime
integer
Time in ms after that the contact state is reseted.
1000

RadioHeadPresenceSensor

RadioHeadPresenceSensor config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress
string
The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress
string
The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.
""
dataPresent
array of strings
Array with the data bytes of the message in hex or dec for the 'present' action. Use * to ignore specific data bytes.
[]
dataAbsent
array of strings
Array with the data bytes of the message in hex or dec for the 'absent' action. Use * to ignore specific data bytes.
[]
autoReset
boolean
Reset the state after resetTime. Useful for contact sensors, that only emit open or close events.
false
resetTime
integer
Time in ms after that the contact state is reseted.
1000

RadioHeadSwitch

RadioHeadSwitch config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
toAddress
string
The address of the receiving device in the RadioHead network in hex or dec. Use 0xFF for broadcasts.
dataOn
array of strings
Array with the data bytes of the message in hex or dec for the 'on' action.
[]
dataOff
array of strings
Array with the data bytes of the message in hex or dec for the 'off' action.
[]
defaultState
boolean
State to set on startup, if not given, last state will be restored

RadioHeadShutter

RadioHeadShutter config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
toAddress
string
The address of the receiving device in the RadioHead network in hex or dec. Use 0xFF for broadcasts.
dataUp
array of strings
Array with the data bytes of the message in hex or dec for the 'move up' action.
[]
dataDown
array of strings
Array with the data bytes of the message in hex or dec for the 'move down' action.
[]
dataStop
array of strings
Array with the data bytes of the message in hex or dec for the 'stop' action.
[]
autoStopTimeUp
integer
Time in milliseconds after which moving up should stop automatically (e.g. 20000). Disabled if using default or 0.
0
autoStopTimeDown
integer
Time in milliseconds after which moving down should stop automatically (e.g. 20000). Disabled if using default or 0.
0

RadioHeadButtonsDevice

RadioHeadButtonsDevice config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
buttons
array of objects
The Buttons.
[]
Elements

RadioHeadWeatherStation

RadioHeadWeatherStation config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress
string
The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress
string
The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.
""
data
array of arrays
You may add multiple messages, if your device is sending different messages for each data.
temperature
The datatype of the transmitted temperature or 'none' if no temperature is used.
"none"
temperatureUnit
string
The unit of the temperature.
"°C"
temperatureProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
humidity
The datatype of the transmitted humidity or 'none' if no humidity is used.
"none"
humidityUnit
string
The unit of the himudity.
"%"
humidityProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
rain
The datatype of the transmitted rain fall or 'none' if no rain fall is used.
"none"
rainUnit
string
The unit of the rain fall.
"mm"
rainProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
windSpeed
The datatype of the transmitted wind speed or 'none' if no wind speed is used.
"none"
windSpeedUnit
string
The unit of the wind speed.
"m/s"
windSpeedProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
windGust
The datatype of the transmitted wind gust or 'none' if no wind gust is used.
"none"
windGustUnit
string
The unit of the wind gust.
"m/s"
windGustProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
windDirection
The datatype of the transmitted wind direction or 'none' if no wind direction is used.
"none"
windDirectionProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
battery
The datatype of the transmitted battery status or 'none' if no battery status is used.
"none"
batteryProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
lowBattery
The datatype of the transmitted low battery status or 'none' if no low battery status is used.
"none"
lowBatteryProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"

RadioHeadCustomSensor

RadioHeadCustomSensor config options
OptionDescriptionDefault
radioHeadSerialPort
string
The ID of RadioHeadSerialPort device to which this device is connected. This device must be created first.
fromAddress
string
The address of the sending device in the RadioHead network in hex or dec. Use 0xFF for all senders.
toAddress
string
The to address of a received message in hex or dec. Defaults to the address of the RadioHeadSerialPort device. Use 0xFF for broadcasts. If the RadioHeadSerialPort device is in promiscuous mode, any message to any address can be received.
""
battery
The datatype of the transmitted battery status or 'none' if no battery status is used.
"none"
batteryProcessing
string
Expression that can preprocess the value, $value is a placeholder for the value itself.
"$value"
customValues
array of objects
You may add multiple custom numeric sensor values.
Elements
customBooleans
array of objects
You may add multiple custom boolean sensor values.
Elements
data
array of arrays
You may add multiple messages, if your device is sending different messages for each data.
pimatic-radiohead is written by Peter Müller (crycode)