Mqtt improvements (#77)

and other major features
spbrogan · Feb 12, 2022 · bb1eaad · bb1eaad
1 parent c17f505
commit bb1eaad
Show file tree

Hide file tree

Showing 16 changed files with 464 additions and 264 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,17 +1,108 @@
 # Configuration
 
-The main idea is that a yaml config file is used as the single parameter for controlling the service
+There are three different files used for configuration.  These are in yaml format (json is valid yaml).  
 
+## Floor plan 1 or 2
 
-## Example
+These two files are both optional but without some floor plan nodes this software doesn't do anything.  These files contain a `floorplan` node and then have subnodes with the different devices in your RV.  A device should only be defined in one floor plan file. The main reason to allow for 
+two input files is to easily support a "HA addon" where a main file might exist and then user entered 
+text from the WebUI might be written to floor plan 2.   
+
+### Example
 
 ``` yaml
-#
-# define the name of the can device
-#
-interface:
-  name: can0
 
+floorplan:
+  - name: DC_LOAD_STATUS
+    instance: 1
+    type: light_switch
+    instance_name: bedroom light
+
+  - name: DC_LOAD_STATUS
+    instance: 2
+    type: light_switch
+    instance_name: living room light
+
+  - name: DC_LOAD_STATUS
+    instance: 8
+    type: light_switch
+    instance_name: awning light
+
+  - name: THERMOSTAT_AMBIENT_STATUS
+    instance: 2
+    type: temperature
+    instance_name: bedroom temperature
+
+  - name: TANK_STATUS
+    instance: 0
+    type: tank_level
+    instance_name: fresh water tank
+
+  - name: TANK_STATUS
+    instance: 1
+    type: tank_level
+    instance_name: black waste tank
+
+  - name: TANK_STATUS
+    instance: 2
+    type: tank_level
+    instance_name: rear gray waste tank
+
+  - name: TANK_STATUS
+    instance: 18
+    type: tank_level
+    instance_name: galley gray waste tank
+
+  - name: TANK_STATUS
+    instance: 20
+    type: tank_level
+    instance_name: what tank is this 20
+
+  - name: TANK_STATUS
+    instance: 21
+    type: tank_level
+    instance_name: what tank is this 21
+
+  - name: WATER_PUMP_STATUS
+    type: water_pump
+    instance_name: fresh water pump
+
+  - name: WATERHEATER_STATUS
+    type: waterheater
+    instance: 1
+    instance_name: main waterheater
+
+  - name: DC_LOAD_STATUS
+    type: tank_warmer
+    instance: 34
+    instance_name: waste tank heater
+
+  - name: DC_LOAD_STATUS
+    type: tank_warmer
+    instance: 35
+    instance_name: fresh water tank heater
+
+```
+
+
+## Log Config File
+
+This is optional and allows for complex logging to be setup.  If provided the yaml file needs to follow 
+<https://docs.python.org/3/library/logging.config.html#logging-config-dictschema>
+
+If not provided the app will do basic docker logging.
+
+
+## Example
+
+This example setups up 3 log files and a basic logger to console.  It assumes you have a volume mapped at 
+`/config` of the container.  
+
+`RVC2MQTT.log` is a basic INFO level logger for the app
+`RVC_FULL_BUS_TRACE.log` will capture all rvc messages (in/out)  
+`UNHANDLED_RVC.log` will capture all the rvc messages that are not handled by an object.
+
+``` yaml
 #
 # Logging info
 # See https://docs.python.org/3/library/logging.config.html#logging-config-dictschema
@@ -25,77 +116,52 @@ logger:
       formatter: brief
       stream: ext://sys.stdout
     debug_file_handler:
-      level: DEBUG
+      level: INFO
       class: logging.FileHandler
       formatter: default
-      filename: rvc_debug.log
+      filename: /config/RVC2MQTT.log
       mode: w
     unhandled_file_handler:
       level: DEBUG
       class: logging.FileHandler
       formatter: time-only
-      filename: unhandled_rvc.log
+      filename: /config/UNHANDLED_RVC.log
       mode: w
-  loggers: 
-    '': # root logger
-      handlers: 
+    rvc_bus_trace_handler:
+      level: DEBUG
+      class: logging.FileHandler
+      formatter: time-only
+      filename: /config/RVC_FULL_BUS_TRACE.log
+      mode: w
+
+  loggers:
+    "": # root logger
+      handlers:
         - debug_console_handler
         - debug_file_handler
       level: DEBUG
       propagate: False
-    'unhandled_rvc':  # special logger for messages not handled
+
+    "unhandled_rvc": # unhandled messages
       handlers:
         - unhandled_file_handler
       level: DEBUG
       propagate: False
+
+    "rvc_bus_trace": # all bus messages
+      handlers:
+        - rvc_bus_trace_handler
+      level: DEBUG
+      propagate: False
+
   formatters:
     brief:
-      format: '%(message)s'
+      format: "%(message)s"
     time-only:
-      format: '%(asctime)s   %(message)s'
-      datefmt: '%Y-%m-%d %H:%M:%S'
+      format: "%(asctime)s   %(message)s"
+      datefmt: "%d %H:%M:%S"
     default:
-      format: '%(asctime)s %(levelname)-8s %(name)-15s %(message)s'
-      datefmt: '%Y-%m-%d %H:%M:%S'
-
-#
-# External Plugins for device entity
-#
-plugins:
-  paths:
-    - /home/pi/config
-#    - <put folder path here for directory of any plugin's you author>
-
-#
-# RV - floor plan
-# This is a list of which devices are in your RV
-#
-# name: must be unique
-map: 
-  - dgn: 1FFBD
-    instance: 1
-    group: '00000000'
-    type: light
-    instance_name: bedroom_light
-  - dgn: 1FFBD
-    instance: 2
-    group: '00000000'
-    type: light
-    instance_name: main_light
-  - dgn: 1FF9C
-    instance: 2
-    type: temperature
-    instance_name: bedroom_temp
-  - name: WATER_PUMP_STATUS
-    type: water_pump
-    instance_name: water pump
+      format: "%(asctime)s %(levelname)-8s %(name)-15s %(message)s"
+      datefmt: "%Y-%m-%d %H:%M:%S"
 
-#
-# MQTT specific settings
-#
-mqtt:
-  broker:   <ip address: port>
-  username: <mqtt username>
-  password: <mqtt password>
-
 ```
diff --git a/docs/docker_deploy.md b/docs/docker_deploy.md
@@ -1,21 +1,41 @@
 # docker
 
 Plan is to deploy using docker. 
-For now you must build your own.
 
-## build it
+Builds are available for released version and `main` branch.
+<https://github.com/spbrogan/rvc2mqtt/pkgs/container/rvc2mqtt>
 
-```bash
-docker build -t rvc2mqtt .
-```
+Image: `ghcr.io/spbrogan/rvc2mqtt:main`
+
+## Settings and configuration
+
+The image uses environment variables for all configuration and file paths.
+
+`CAN_INTERFACE_NAME` : the network can interface name.  default value: `can0`
+
+`FLOORPLAN_FILE_1` : path to the floor plan file.  Recommendation is mount a volume from the host with your floor plan
+
+`FLOORPLAN_FILE_2` : path to the 2nd floor plan file.  This is optional but for HA addons this allows UI generated content to be added.
+
+`LOG_CONFIG_FILE` : path to a logging configuration file.  Optional yaml file for more complex logging options.
 
-## config file
+`MQTT_HOST` : host url for mqtt server
 
-The image expects a config file located at /config/config.yaml
-You should bind a host directory to this with your config.yaml.
-It also works well for your log files
+`MQTT_PORT` : host port for mqtt server
 
-See configuration.md for a sample config.yaml
+`MQTT_USERNAME` : username to connect with
+
+`MQTT_PASSWORD` : password to connect with
+
+`MQTT_CLIENT_ID` : mqtt client id and the bridge node name in mqtt path.  default is `bridge`
+
+Optional values if using TLS (not implemented yet!)
+
+`MQTT_CA` : CA cert for Mqtt server  
+`MQTT_CERT` : Cert for client  
+`MQTT_KEY` : key for mqtt
+
+See configuration.md for a sample files are more details.
 
 ## run it
 
@@ -25,16 +45,14 @@ Might need to bring up the can0 interface on host like
 
 ```bash
 sudo ip link set can0 down
-sudo ip link set can0 up type can bitrate 250000
+sudo ip link set can0 up type can
 ```
 Then to run the docker image
 
-```bash
-docker run --network=host --restart=always -v ~/config:/config rvc2mqtt 
-```
+you will need to setup a bunch of env variables so the command is pretty length.  Sorry.  A docker compose file would probably be helpful.
 
-## run in the container yourself
+## build it locally
 
 ```bash
-docker run --network=host --restart=always -v ~/config:/config -it rvc2mqtt bash
+docker build -t rvc2mqtt .
 ```
diff --git a/docs/hardware.md b/docs/hardware.md
@@ -23,10 +23,9 @@ This has been used on Raspberry Pi OS Lite
 
 ### Enable CanBus support in Kernel
 
-* Add waveshare doc and steps here
-* <https://www.waveshare.com/w/upload/2/29/RS485-CAN-HAT-user-manuakl-en.pdf>
+See the waveshare doc here: <https://www.waveshare.com/w/upload/2/29/RS485-CAN-HAT-user-manuakl-en.pdf>
 
-Need to update /boot/config.txt to enable rs485 can hat
+### Update /boot/config.txt to enable rs485 can hat
 
 If you are using HomeAssistantOS you will need to remove the SD card and find the file on the boot partition.  
 
@@ -47,16 +46,16 @@ TBD - figure out how to do automatically.  Too many different linux network serv
 Manually this can be done doing
 
 ``` bash
-sudo ip link set can0 type can bitrate 250000
+sudo ip link set can0 type can
 
 sudo ip link set can0 up
 ```
 
-### Make a config.yaml file in a folder you can mount as /config for the container
+### Make a floorplan.yaml file and/or logging.yaml in a folder you can mount as /config for the container
 
 See [configuration.md](configuration.md)
 
-### Build and deploy with docker
+### deploy with docker
 
 see docker_deploy.md
 

diff --git a/docs/mqtt.md b/docs/mqtt.md
@@ -16,14 +16,7 @@ This schema can support multiple rvc2mqtt bridges
 using the client-id to provide an isolated namespace.  Please make sure this is unique if you
 have more than one bridge 
 
-```yml
-mqtt:
-  broker:    <ip address>:<optional port>
-  username:  <user name>
-  password:  <password>
-  client-id: <client-id> #optional default=bridge
-
-```
+Setting the config for MQTT can be done as command line parameters or thru environment variables.  For Docker env is suggested.
 
 ## Topic hierarchy
 
@@ -33,21 +26,21 @@ is located at here:
 `rvc2mqtt/<client-id>`  
 
 More specifically:
-`rvc2mqtt/<client-id>`       - this reports the connected state of our bridge to the mqtt broker (`online` or `offline`)
+`rvc2mqtt/<client-id>/state`       - this reports the connected state of our bridge to the mqtt broker (`online` or `offline`)
 `rvc2mqtt/<client-id>/info`  - contains json defined metadata about this bridge and the rvc2mqtt software
 
 Devices managed by rvc2mqtt are listed by their unique device id
 `rvc2mqtt/<client-id>/d/<device-id>`
 
-### Light
+### Light Switch
 
-The Light object is used to describe a light.
+The Light Switch object is used to describe an switch.
 A light can have on / off
 
 | Topic             | rvc2mqtt operation | Description                     |
 |---                | :---:              | ---                             |
-|`<device-id>`      | publish            | status of light (`on` or `off`) |
-|`<device-id>cmd`   | subscribe          | command the light with payload `on` or `off` |
+|`<device-id>/state`| publish            | status of light (`on` or `off`) |
+|`<device-id>/cmd`  | subscribe          | command the light with payload `on` or `off` |
 
 
 
@@ -60,7 +53,7 @@ It only updates the mqtt topic when the temperature changes.
 
 | Topic                         | rvc2mqtt operation | Description                     |
 |---                            | :---:              | ---                             |
-|`<device-id>`      | publish            | temperature in C |
+|`<device-id>/state`            | publish            | temperature in C |
 
 
 ### HVAC
@@ -75,11 +68,12 @@ Home assistant has created mqtt auto-discovery.  This describes how rvc2mqtt int
 with mqtt auto-discovery.
 
 
-follows path like: <discovery_prefix>/<component>/[<node_id>/]<object_id>/config
-
-<homeassistant> is the discovery prefix
+follows path like: `<discovery_prefix>/<component>/<unique_device_id>/<entity_id>/config`
 
-<node_id> will be a bridge <client-id> this is needed because if two bridges talk to same server there could be conflicting ids
+`homeassistant` is the discovery prefix  
+`component` is one of the home assistant component types  
+`unique_device_id` is the sensors unique id.  This will be a concatination that includes the rvc2mqtt_client-id_object  
+`entity_id` is the entity id within the device
 
-payload is json that matches HA config (at least all required)
+config payload is json that matches HA config (at least all required)