Skip to content
A python based service that receives sensor inputs and publishes them over REST (should work with any API but mainly tested with openHAB) or MQTT. It can also receive commands and perform an action (e.g. set a GPIO pin to HIGH). It currently supports Bluetooth, GPIO on Raspberry Pi, Amazon Dash buttons, command line scripts, and Roku IP address …
Python Shell
Branch: master
Clone or download
rkoshak Modified the behavior for all sensors to always publish their last st…
…ate upon receiving the update message even if they do not have a polling period.
Latest commit 581dee6 Aug 13, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Modified the behavior for all sensors to always publish their last st… Aug 13, 2019
.gitignore Ignore vim swp files May 24, 2018 Make GPIO connection class Dec 20, 2017
LICENSE Initial commit Jun 18, 2015 Added an execSensor, compliments the execActuator Jun 6, 2018 Add arpscanner Sep 25, 2018 Made Python Bluez option when using BTLE mode. Solves #52. May 24, 2018 Couple of late changes Dec 22, 2017
default.ini Client in the Connection section needs to be capitalized Nov 14, 2018 I used the wrong type of slash when excluding comments in the script … Jun 6, 2018 Added an execSensor, compliments the execActuator Jun 6, 2018 Cleaned up some logging, backed out the qos setting on subscribe beca… May 24, 2018 Cleaned up some logging, backed out the qos setting on subscribe beca… May 24, 2018 Fixed indent issue caused by empty def May 17, 2018 Finish up changes for GPIO connection Dec 22, 2017 Undid the last change. Stupid mistake. Set the default logging level … Jun 14, 2018 Add alternative publish values to sensor Jan 20, 2018 Modified the behavior for all sensors to always publish their last st… Aug 13, 2019 Modified the behavior for all sensors to always publish their last st… Aug 13, 2019 Reworked to be completely generic so it no longer n… Aug 25, 2016 Make GPIO connection class Dec 20, 2017


A Python script that bridges sensors and actuators to MQTT and/or REST. It was written to support integrating remote sensors with openHAB 1.x, but it should support any remote hub that has a simple REST API or uses MQTT.

The script currently supports MQTT and openHAB 1.x's REST API for publishing sensor readings and actuator results. It supports MQTT for receiving commands to activate actuators.

The currently supported technologies are: Raspberry PI GPIO sensors and actuators, Bluetooth presence detection sensors, Dash Button presses, Roku IP address discovery, executing command line programs, DHT11/22 senors, and a hearbeat publisher.


The main script is this script parses the configuration ini file and implements the main polling loop and thread management. During startup this script reads the ini file and creates instances of the indicated classes and passes them the arguments for that class.

The script has been made generic and easily expanded through plugins. To add a new sensor or actuator simply put the new class file(s) in the same folder, fill out the ini file section and sensorReporter will handle the rest. There is no longer a need to edit to add new capability. The same is true for Connections.


The core of the script does not have any dependencies. However each plugin may have its own dependencies.

MQTT depends on the Paho library.

The Native Raspberry Pi GPIO library comes with Raspbian by default and requires sensorReporter be run as root or by as user who is a member of the GPIO group.

Bluetooth depends on bluez, python-bluez and bluepy (for bluetooth LE scanning).

Dash requires scapy and it requires sensorReporter be run as root

Roku does not require anything special be installed.

Execute actuator requires subprocess32 if executed on a Posix system with Python 2.7

DHT11/22 requires the Adafruit DHT library.

The in the config folder lists all the commands necessary to install dependencies, link the current folder to /opt and set it up to start as a service. It has the scripts and commands for both upstart and systemd. However, this script is not intended to be run as is and instead is intended as a guide.


The config folder contains an as described above, sensorReporter start script for upstart systems (e.g raspbian wheezy), and a service file for systemd type systems (e.g raspbian jessey, Ubuntu 15+). The install script shows the install steps to get the dependencies using using apt-get and pip and to copy and enable the start script to init.d so sensorReporter will start as a service during boot. You must edit the script to match your system. This script is intended to be informational, not to be executed as is.

The main folder has a default.ini with configuration parameters and the Python script itself. The default.ini has example configurations for all of the supported addons with some comments to describe the parameter's meanings.

The expects there to be a .ini file that matches your hostname. It will create a symbolic link to sensorReporter.ini. However, is intended to illustrate the install process and not to be run as is.

If you place or link the script somewhere other than /opt/sensorReporter you need to update the sensorReporter start script or sensorReporter.service with the correct path.


default.ini is the primary documentation for each plugin's configuration. All the supported options and what they mean is documented in the comments.

The configuration file contains one or more Sensor and/or Actuator sections which specify their Type, the MQTT/REST destination to report to, communciation type (MQTT or REST), and sensor/actuator specific info (e.g. pin, BT address, etc.).

The Logging section allows one to specify where the scripts log file is saved, its max size, and maximum number of old log files to save. When Syslog is enabled all logging goes to the system syslog instead.

The REST section is where one specifies the beggining portion of the URL for the REST API. For openHAB, this is the full REST URL to the Item without the Item name. The Item name is specified as the destination in the sensor/actuator sections.

The MQTT section is where one specifies the user, password, host, and port, for the MQTT Broker. The Topic item in this section is a topic the script listens to report the state of the sensors on command (i.e. any message sent to this topic will cause sensorReporter to publish the current state of all its configured sensors. One also defines a Last Will and Testament topic and message so other servers can monitor when sensorReporter goes offline.

Note that Actuators only support MQTT communicators.


To run the script manually:

sudo python sensorReporter sensorReporter.ini

If it has been configured as a service, run:

sudo service sensorReporter start


sudo systemctl start sensorReporter


The script will poll the sensors once per configured poll period. If the state of the sensor has changed since the last poll the state is published on the configured MQTT/REST destination.

The GPIO sensor pins will report "OPEN" for active pins and "CLOSED" for inactive pins.

The Bluetooth scanner will report "ON" when the device is present and "OFF" when it is not. Bluetooth LE scanning is tested with a Gigaset G-tag but should work with any tag. It checks only for presence of the device, the parameters are not used. If the device is found, a keyword will be reported. The keywords can be modified in the ini file, default values are "ON" and "OFF".

Dash will report "Pressed" when it detects the button press.

The Roku scanner will publish the detected IP address for that Roku.

The exec actuator will publish the result printed by the executed script, or ERROR if the script didn't return a 0 exitcode.

The heartbeat sensor will publish the uptime in milliseconds to destination/number and the uptime in DD:HH:MM:SS to destination/string once per polling period.

Upon receipt of any message on the main incoming destination, the script will publish the current state of all configured polling sensors (sensors with a polling period > 0) on their respective destinations immediately. Those with a 0 polling period will not report their current status.

The script is configured to respond properly to term signals (e.g. <ctrl>-c) so it behaves nicely when run as a service (currently broken when using Dash).

Bluetooth Specifics

To discover the address of your Bluetooth device (e.g. a phone), put it in pairing mode, run and record the address next to the name of your device. Use this address in the .ini file for your Bluetooth scanning sensors. is part of the pybluez project and can be found at

Dash Button Specifics

To discover the address of your Dash button, there is a script in the config folder that will run for a short time and print the MAC address of any device that issues an ARP request while it is running. Run the script and then press the button and it will print that button's address. If you are in a noisy network with lots of ARP requests you may need to do trial and elimination to discover which MAC is for your button. Both of my buttons start with 74 but I don't know if that is a pattern that holds across all buttons.

Upon receiving your Dash button, follow the configuration steps up to the point where it asks you to choose a product. Close the setup app at this point and whenever you press the button the request will fail (i.e. you won't order anything) but it will be able to join your network and issue the ARP request we use to tell when it is pressed.

The code and approach to using Dash is inspired from the example found at

Follow the default.ini example to map the MAC address to a destination. When sensorReporter detects the ARP packet from that button it will send the string "Pressed" to the corresponding destination. For example, if you have an Address1, it will send "Pressed" to Destination1.

Note that in openHAB 2 there is now a Dash binding which you should use instead.

Roku Specifics

The "Name" of the Roku is the device's serial number. This can be found printed on the label on the bottom of your Roku device or found in the "My linked devices" section on your account page.

DHT Specifics

Supported DHT sensors is DHT22, it can either run in Advanced Mode or Simple Mode. In Simple mode it just reads data from the sensor, and verifies that it is between bounds and returns the reading.

In Advanced mode it reads the value and stores last five readings in an array. The returned value is the mean value of the readings in the array. This approach can be used if you encounter some readings that are wrong every now and then.

Be sure that Adafruits DHT Python library is installed, instructions can be found at

Exec Specitics

The exec sensor will periodically execute the given shell script and publish the result or 'ERROR' if the script didn't return a 0 exitcode to the configured destination. Avoid making the polling period shorter than it takes the script to run in the worst case or else you will run out of threads to run the sensorReporter.

You can’t perform that action at this time.