{"id":13908175,"url":"https://github.com/rkoshak/sensorReporter","last_synced_at":"2025-07-18T07:30:37.744Z","repository":{"id":33942785,"uuid":"37668254","full_name":"rkoshak/sensorReporter","owner":"rkoshak","description":"A python based service that receives sensor inputs and publishes them in various ways.","archived":false,"fork":false,"pushed_at":"2025-05-30T19:41:18.000Z","size":693,"stargazers_count":106,"open_issues_count":2,"forks_count":41,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-05-31T04:52:39.071Z","etag":null,"topics":["bluetooth","gpio","mqtt","openhab","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"henrylee2cn/pholcus_lib","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rkoshak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["rkoshak"],"custom":["https://paypal.me/rlkoshak"]}},"created_at":"2015-06-18T15:34:57.000Z","updated_at":"2025-05-30T19:41:22.000Z","dependencies_parsed_at":"2023-01-15T03:30:52.140Z","dependency_job_id":"44753081-36bd-4c29-ab0c-080e6fd4d027","html_url":"https://github.com/rkoshak/sensorReporter","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rkoshak/sensorReporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rkoshak%2FsensorReporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rkoshak%2FsensorReporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rkoshak%2FsensorReporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rkoshak%2FsensorReporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rkoshak","download_url":"https://codeload.github.com/rkoshak/sensorReporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rkoshak%2FsensorReporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265720346,"owners_count":23817213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bluetooth","gpio","mqtt","openhab","rest-api"],"created_at":"2024-08-06T23:02:31.482Z","updated_at":"2025-07-18T07:30:37.728Z","avatar_url":"https://github.com/rkoshak.png","language":"Python","funding_links":["https://github.com/sponsors/rkoshak","https://paypal.me/rlkoshak"],"categories":["HarmonyOS","General Tools"],"sub_categories":["Windows Manager","Independent \u0026 Hobbyist Projects"],"readme":"# sensor_reporter\nsensor_reporter is a Python 3 script that bridges sensors and actuators to MQTT or openHAB's REST API.\nIt's a modular script that allows for relatively easy implementation of new capabilities with minimal effort.\nIf you've used sensorReporter or mqttReporter before, this is a complete rewrite with many breaking changes.\nSee the release notes below for details.\n\nA number of connections, sensors, and actuators are currently supported.\n- Connection: responsible for publishing sensor readings and actuator results and subscribing for actuator commands.\n- Actuators: classes that perform some action when a message is received.\n- Polling Sensors: classes that query some device on a set polling period.\n- Background Sensors: classes that sense for events in the background and do not require polling.\n\nGo into the subfolders for details in each subfolder's README.\n\n| Plug-in                                                                                                   | Type                         | Purpose                                                                                                   |\n|-----------------------------------------------------------------------------------------------------------|------------------------------|-----------------------------------------------------------------------------------------------------------|\n| [`bt.btle_sensor.BtleSensor`](bt/README.md#btbtle_sensorbtlesensor)                                       | Background Sensor            | Scans for BTLE advertisements from configured devices.                                                    |\n| [`bt.btscan_sensor.SimpleBtSensor`](bt/README.md#btbtscan_sensorsimplebtsensor)                           | Polling Sensor               | Scans for the presence of BT devices with a given addresses.                                              |\n| [`bt.govee_sensor.GoveeSensor`](bt/README.md#btgovee_sensorgoveesensor)                                   | Background Sensor            | Receives BTLE packets from Govee H5075 temperature and humidity sensors.                                  |\n| [`energymeter.read_meter_values.Pafal20ec3gr`](energymeter/README.md#pafal_readerpafal_readerpafalreader) | Polling Sensor               | Periodically reads out an energymeter using serial device. Currently only Pafal 20ec3gr supported.        |\n| [`exec.exec_actuator.ExecActuator`](exec/README.md#execexec_actuatorexecactuator)                         | Actuator                     | On command, executes the configured command line command.                                                 |\n| [`exec.exec_sensor.ExecSensor`](exec/README.md#execexec_sensorexecsensor)                                 | Polling Sensor               | Executes the configured command line and publishes the result.                                            |\n| [`gpio.dht_sensor.DhtSensor`](gpio/README.md#gpiodht_sensordhtsensor)                                     | Polling Sensor               | Publishes temperature and humidity readings from DHT11, DHT22, and AM2302 sensors connected to GPIO pins. |\n| [`gpio.rpi_gpio.RpiGpioSensor`](gpio/README.md#gpiorpi_gpiorpigpiosensor)                                 | Polling or Background Sensor | Publsihes ON/OFF messages based on the state of a GPIO pin.                                               |\n| [`gpio.rpi_gpio.RpiGpioActuator`](gpio/README.md#gpiorpi_gpiorpigpioactuator)                             | Actuator                     | Sets a GPIO pin to a given state on command.                                                              |\n| [`gpio.gpio_led.GpioColorLED`](gpio/README.md#gpiogpio_ledgpiocolorled)                                   | Actuator                     | Commands 3 to 4 GPIO pins to control a RGB or RGBW LED                                                    |\n| [`heartbeat.heartbeat.Heartbeat`](heartbeat/README.md#heartbeatheartbeatheartbeat)                        | Polling Sensor               | Publishes the amount of time sensor_reporter has been up as number of msec and as DD:HH:MM:SS.            |\n| [`local.local_conn.LocalConnection`](local/README.md#local-connection)                                    | Connection                   | Allows sensors to call actuators.                                                                         |\n| [`local.local_logic.LogicOr`](local/README.md#locallocal_logiclogicor)                                    | Actuator                     | Forwards commands from multiple inputs locally to an actuator.                                            |\n| [`mqtt.mqtt_conn.MqttConnection`](mqtt/README.md#mqtt-connection)                                         | Connection                   | Allows Actuators to subscribe and publish and Sensors to publish results to a MQTT server.                |\n| [`mqtt.homie_conn.HomieConnection`](mqtt/README.md#homie-connection)                                      | Connection                   | Subscribe and publish sensors and actuators to a MQTT server via Homie convention.                        |\n| [`network.arp_sensor.ArpSensor`](network/README.md#networkarp_sensorarpsensor)                            | Polling Sensor               | Periodically gets and parses the ARP table for given mac addresses.                                       |\n| [`network.dash_sensor.DashSensor`](network/README.md#networkdash_sensordashsensor)                        | Background Sensor            | Watches for Amazon Dash Button ARP packets.                                                               |\n| [`one_wire.ds18x20_sensor.Ds18x20Sensor`](one_wire/README.md#one_wireds18x20_sensords18x20sensor)         | Polling Sensor               | Publishes temperature reading from DS18S20 and DS18B20 1-Wire bus sensors connected to GPIO pins.         |\n| [`openhab_rest.rest_conn.OpenhabREST`](openhab_rest/README.md#openhab-rest-connection)                    | Connection                   | Subscribes and publishes to openHAB's REST API. Subscription is through openHAB's SSE feed.               |\n| [`roku.roku_addr.RokuAddressSensor`](roku/README.md#roku-address-sensor-deprecated)                       | Polling Sensor               | Periodically requests the addresses of all the Rokus on the subnet.                                       |\n| [`ic2.relay.EightRelayHAT`](i2c/README.md#i2crelayeightrelayhat)                                          | Actuator                     | Sets a relay to a given state on command. Supports 8-Relays-HAT via i2c                                   |\n| [`ic2.triac.TriacDimmer`](i2c/README.md#i2ctriactriacdimmer)                                              | Actuator                     | Sets a triac PWM to a given duty cycle on command. Supports 2-Ch Triac HAT via i2c                        |\n| [`i2c.pwm.PwmHatColorLED`](i2c/README.md#i2cpwmpwmhatcolorled)                                            | Actuator                     | Commands 3 to 4 Channels on a PWM HAT to control a RGB or RGBW LED                                        |\n| [`i2c.aht20.AHT20Sensor`](i2c/README.md#i2caht20aht20sensor)                                              | Polling Sensor               | Publishes temperature and relative humidity reading from an AHT20 sensor connected to the i2c bus.        |\n\n# Architecture\nThe main script is `sensor_reporter.py` which parses a configuration YAML file and handles operating system signal handling.\n\nIt uses a `core.poll_mgr.PollMgr` manages running a polling loop used by Polling Sensors to control querying the devices.\n\nAll connections inherit from `core.connection.Connection`.\nAll Actuators inherit from `core.actuator.Actuator` and all sensors inherit from `core.sensor.Sensor`.\nCommon code is implemented in the parent classes.\n\nOn startup or when receiving a `HUP` (`kill -1`) operating system signal the configuratuion YAML file is loaded.\nThere is a logging section (see below) where the logging level and where to log to is defined.\nThen there is a separate section for each connection, sensor, and actuator.\nEach individual plug-in will define it's own set of required and optional parameters.\nSee the README files in the subfolders for details.\n\nHowever, some parmeters will be common.\n- All polling sensors require a Poll parameter indicating how often in seconds to poll the sensor devices\n- All sections require a Class parameter defining the class to load.\n- All sensors and actuators require a Connections class containing a dictionary with the connections and topics to publish/subscribe through. The layout is described at the connections readme.\n- All actuators require a command source, which has to be unique for the configured connection. E. g. if the same command source is used by several actuators only the last one will work. The parameter name of the command source varies differently for each connection.\n- All sections have an optional Level parameter where the logging level for that plugin or sensor_reporter overall can be set. Supported levels are DEBUG, INFO, WARNING, and ERROR.\n\n# Dependencies\nsensor_reporter only runs in Python 3 and has only been tested in Python 3.7 through Python 3.11.2.\nIt uses PyYAML for parsing the configuration file.\n\n## Setup\nAfter cloning this repo to a folder (e.g. `/srv/sensorReporter`) run the following commands:\n\n```bash\ncd /srv/sensorReporter\nsudo ./setup.sh\n```\nThis will install the base dependencies and setup a virtualenv for the Python packages.\nEach plug-in will have it's own dependency.\nSee the readme's in the subfolders for details.\n\n## Optional plug-in dependencies\nPlug-in dependencies can be installed on demand using the install_dependencies.sh from the base folder:\n\n```bash\ncd /srv/sensorReporter\nsudo ./install_dependencies.sh \u003cplug-in folders separated by ','\u003e\n```\nFor example, install the mqtt and bt (bluetooth) dependencies:\n```bash\nsudo ./install_dependencies.sh mqtt,bt\n```\nFor more examples see plug-in readme's.\nRun command without parameters to list available plug-ins.\n\n# Usage\n\n1. Download sensor_reporter and execute setup.sh see section [setup](#setup)\n2. Write your configuration file and save it to `/srv/sensorReporter/sensor_reporter.yml`. For details see section [configuration](#configuration) and the plug-in readme's\n3. Start sensor_reporter manually to test the configuration with:\n\n```bash\ncd /srv/sensorReporter\nbin/python sensor_reporter.py sensor_reporter.yml\n```\n(optional) enable \u0026 start the service:\n\n4. set service to auto start:  `sudo systemctl enable sensor_reporter.service`\n5. start sensor_reporter:  `sudo systemctl start sensor_reporter.service`\n\nTo reload a modified sensor_reporter.yml use the command:  `sudo systemctl reload sensor_reporter.service`  \nAfter large changes to the configuration, e. g. sensors/actuators has been removed/added, a restart of the service is recommended.\n\n# Configuration\nsensor_reporter uses an YAML file for configuration.\nThe only required section is the logging section.\nHowever, to do anything useful, there should be at least one Connection and at least one Sensor or Actuator.\nAll logging will be published to standard out.\nIn addition logging will be published to syslog or to a log file.\n\n*Security advice:* make sure your sensor_reporter.yml is owned by the user `sensorReporter` and only that user has read and write permissions.\nThis user is automatically created when choosing 'install service' in setup.sh.\n\n`sudo chown sensorReporter:nogroup sensor_reporter.yml`  \n`sudo chmod 600 sensor_reporter.yml`\n\n## Syslog Example\n\n```yaml\nLogging:\n    Syslog: yes\n    Level: INFO\n```\n`Syslog` can be any boolean value, including yes / no.\nWhen true no other parameters are required.\n`Level` is the default logging level for the core parts of sensor_reporter and any plug-in that doesn't define it's own `Level` parameter. Allowed values: `DEBUG, INFO, WARNING, ERROR`\n\n## Log File Example\n\n```yaml\nLogging:\n    File: /var/log/sensor_reporter/sensorReporter.log\n    MaxSize: 67108864\n    NumFiles: 10\n    Syslog: no\n    Level: INFO\n```\n`File` is the path to the log file.\n`MaxSize` is the maximum size of the log file in bytes before it gets rotated.\n`NumFiles` is the number of old log files to save, older files are automatically deleted\n\nThe above parameters are only required if `SysLog` is disabled.\n`Level` is the same as for `Syslog: yes` and indicates the default logging level.\n\nMake sure the user `sensorReporter` has write access:\n1. `sudo mkdir /var/log/sensor_reporter`\n2. `sudo chown sensorReporter:nogroup /var/log/sensor_reporter`\n\n## Sections for Components\n\nNote that sensor_reporter requires the section names to start with the type of the plugin.\nPossible values are:\n* Connection\n* Actuator\n* Sensor\n\nA sensor section could thus be named `Sensor_Heartbeat` or `Actuator1`.\nSection names have to be unique.\n\n## Default section\n\nOptionally a `DEFAULT` section can be added to the configuration.\nParameters within this section will be the default for all sensors and actuator.\nSensors and actuators can override the default if they specifie the same parameter.\nThis is useful when many sensors of the same type with similar parameters are used.\nE. g. set the default for `TempUnit` so the DhtSensors don't need to specifie it repetitive:\n\n```yaml\nDEFAULT:\n    TempUnit: F\n```\n\n# Release Notes\nThis current version is a nearly complete rewrite of the previous version with a number of breaking changes.\n\n## Breaking Changes\n\n- Moved Ds18x20Sensor to folder one_wire, so the Class path has changed - May 2024\n- RpiGpioSensor, RpiGpioActuator and GpioColorLED pins can only be configured using Broadcom pin numbering (GPIO numbers) - April 2024\n- The configuration file is now in YAML syntax instead of a ini file - October 2022\n- Sending a `kill -1` now causes sensor_reporter to reload it's configuration instead of exiting\n- No longer runnable on Python 2, tested with Python 3.7.\n- All sensors inherit from the `core.sensor.Sensor` class and the constructor now only takes two arguments\n- All actuators inherit from the `core.actuator.Actuator` class and the constructor now only takes two arguments\n- `bluetooth.py` has been split into three separate sensor classes instead of just the one overly complicated one. There is now the BTLE Sensor, the Simple BT sensor, and the BT RSSI sensor to replace it and support the three modes.\n- Across the board improved error logging and reporting.\n- The set of required and optional parameters has changed for all sensors, actuators, and connections.\n- The DHT Sensor is rewritten to use the new adafruit-blinkie library as the Adafruit_DHT library is deprecated.\n- The RPi GPIO sensor no longer directly supports calling actuators or handlers. Instead the Local connection replaces this capability in a more generic way that works for all sensors. Rather than creating a handler, create an Actuator and connect a sensor to the Actuator by adding a Local connection to both.\n- The LWT topic and message is now hard coded as is the refresh topic. When sensor_reporter connects it publishes ONLINE as a retained message to the LWT topic. When closing down or as a LWT OFFLINE is posted as a retained message.\n- The REST communicator has been made specific to openHAB, but added the ability to work in both directions. sensor_reporter can now receive messages by commanding openHAB Items in addition to updating Items.\n\n## Other changes\n\n- Several connectors now support a disconnect/reconnect action for sensors/actuators\n- RpiGpioActuator and GpioColorLED now uses lgpio library\n- RpiGpioSensor now uses lgpio library (fixes edge detection not working on kernel 6.6)\n- Logs out to standard out in addition to Syslog or log files.\n- Reogranized singal handleing to make it simpler.\n- Moved the polling to a separate class.\n- If a sensor is still running from a previous poll period, the next poll will be skipped until the sensor polling completes.\n- Bluetooth LE now supports more than one device per sensor.\n- The exec sensor and exec actuator now support timeouts to keep a command line from hanging forever. The exec sensor is hard coded to 10 seconds. The exec sensor has a parameter that can be set in the ini file.\n- Added a Local connection which lets sensors send messages to Actuators. For example, a temperature sensor can turn on an LED light when the temperature is above a threshold.\n- Improved error reporting and added a timeout to the arp sensor.\n- Dash sensor has been rewritten to use the Scapy AsynchSniffer which fixes the problem where the sensor blocks sensor_repoter from exiting on a kill signal.\n- Conforms to pylint PEP-8 where feasable.\n- Signigficatin reduction in duplicated code and hopefully the overall structure and way it works is more straight forward.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frkoshak%2FsensorReporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frkoshak%2FsensorReporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frkoshak%2FsensorReporter/lists"}