rpicontrol/README.md

Raspberry MQTT Control
=====================

## Description
This is a linux daemon application for Raspberry PI, which receives control commands via MQTT to set GPIO ports of Raspberry.
As MQTT is widely supported within different home automation systems, this daemon application should be quite easily be integrated, for example in [OpenHAB](https://www.openhab.org/)
For further information, how to configure and use OpenHAB MQTT Binding, please see [here](https://www.openhab.org/addons/bindings/mqtt.generic/)

## Usage
This application is fully controlled via MQTT Pub/Sub mechanism.
- To test the behavior, install and start an MQTT broker the linux daemon *rpicontrol*, as described in chapter _Installation_.
- As soon as everything is running, you can test the switch of output pins via following command:
  
  `mosquitto_pub -h localhost -t /rpicontrol/gpio/out1/control -m ON`

  This command will set the configured GPIO pin with name *out1* to state _ON_. 
  State _OFF_ will also work of course.

  - this command refers to example config as described below. If you have configured different pin names, broker address, or topic prefix, 
    you have of course to adapt the command according to your configuration.
- In order to see current states of all configured GPIO pins, you can subscribe via wildcard to the MQTT topic:

  `mosquitto_sub -h localhost -t "/rpicontrol/#" -v`
  - Again, this command refers to example config as described below. If you have configured different pin names, broker address, or topic prefix, you have of course to adapt the command according to your configuration.
  
  
 

## Installation
- Install and configure an appropriate MQTT broker either locally or on your network.
  for this, the open-source broker [mosquitto](https://mosquitto.org/) will be a good choice. 
  For installing and configuring mosquitto for your platform, please see the mosquitto docs.

- untar the package tarball with following command:
  
  `sudo tar xfvz -C / rpicontrol-a.b.c.tar.gz`, where _a.b.c_ represents the version of rpicontrol

- use the example config file as initial configuration
  
  ```
  cp /etc/rpicontrol/rpicontrol.conf.example /etc/rpicontrol/rpicontrol.conf
  ```
- edit the configuration file `/etc/rpicontrol/rpicontrol.conf` to your needs, see chapter _Configuration_

- reload systemd, enable and start service:

  ```
  sudo systemctl daemon-reload
  sudo systemctl enable rpicontrol.service
  sudo systemctl start rpicontrol.service
  ```


## Configuration

### Example Configuration
Configuration file has YAML syntax, and shall have following structure.
Please note that optional values are not needed for configuration, see _Available Parameters_


```
mqtt-config:
  broker-address: "tcp://localhost:1883"
  connect-timeout-ms: 10000 
  connect-retry-interval-ms: 10000
  max-reconnect-interval-ms: 10000
  topic-prefix: "/rpicontrol"
  username: "rpicontrol"
  password: "my_password"

pin-control-config:
  gpio-pins:
    - number: 17                             
      name: out1
      direction: Output
      pull-config: PullOff
      send-polling-events: false
      send-change-events: true
      initial-state: "OFF"

  polling-time-ms: 100
```
### Available Parameters

- **mqtt-config**: section for configuring MQTT Broker Connection
  - **broker-address**: URL for MQTT Broker. Example Value: "tcp://localhost:1883"
  - **connect-timeout-ms**: (optional) timeout in milliseconds for connection
  - **connect-retry-interval-ms**: (optional) connection retry interval in milliseconds
  - **max-reconnect-interval-ms**: (optional) max connection retry interval time in milliseconds
  - **topic-prefix**: (optional) prefix for MQTT topic 
  - **username**: (optional) username for MQTT connection
  - **password**: (optional) password for MQTT connection

- **pin-control-config**: section for configuring GPIO Pins that shall be used
  - **gpio-pins**: list of GPIO pins
    - **number**: number of GPIO pin, see [Raspberry Pi: GPIO - General Purpose Input Output](https://www.elektronik-kompendium.de/sites/raspberry-pi/2002191.htm)
    - **name**: custom name for the pin (used for MQTT topic).
    - **direction**: configure GPIO direction. Available Values: Input, Output
    - **pull-config**: configure GPIO pull-up/down resistor. Available Values:
      - PullDown: pull-down resistor
      - PullUp: pull-up resistor
      - PullOff: no resistor
    - **send-polling-events**: (optional) send pin state via MQTT on every polling event. Available Values:
      - true: enable send on polling event
      - false (default): disable send on polling event
    - **send-change-events**: (optional) send pin state via MQTT on a change event. Available Values:
      - true: enable send on change events
      - false (default): disable send on change events
    - **initial-state**: (optional) set of initial state of output pin at start of application. Available Values:
      - ON: initial state set to ON at startup
      - OFF: initial state set to OFF at startup
      - [not set]: do not set initial state at startup
  - **polling-time-ms**: (optional) interval in milliseconds (default: 100), for cyclically polling the current state of all pins.