Update documentation for V2.7.0

enwi · Jul 30, 2022 · 410a2ec · 410a2ec
1 parent 96813fb
commit 410a2ec
Show file tree

Hide file tree

Showing 4 changed files with 181 additions and 59 deletions.
diff --git a/README.md b/README.md
@@ -17,13 +17,17 @@ Documentation and guides for RNGBridge V2, an RS232 to WiFi bridge for Renogy so
  - Works with protected Brokers (`username`, `password`)
  - Configurable `topic`, `client id`, `port` and `ip`
  - Configurable update interval (since [V2.3.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.3.0))
+ - Control `Load`, `Out1`, `Out2` and `Out3` (since [V2.7.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.7.0))
+ - Supports [Homeassistant Discovery](https://www.home-assistant.io/docs/mqtt/discovery/) (since [V2.7.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.7.0))
 - Optional data publishing to [PVOutput](https://pvoutput.org)
  - Configurable time offset
 - Automatic `Load`, `Out1`, `Out2` and `Out3` control
  - lower/upper setpoint
  - can be inverted
  - control depending on battery SOC(state of charge), battery voltage, panel voltage (since [V2.6.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.6.0)) or panel current (since [V2.6.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.6.0))
-- [Control `Load`, `Out1`, `Out2` and `Out3` through REST api](https://github.com/enwi/RNGBridgeDoc/blob/main/rest.md)
+- [REST API](https://github.com/enwi/RNGBridgeDoc/blob/main/rest.md)
+ - Control `Load`, `Out1`, `Out2` and `Out3`
+ - Request current charge controller state (since [V2.7.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.7.0))
 
 Missing anything? If you want support for a custom feature or want to suggest something, feel free to open an issue or join the [Discord Server](https://discord.gg/YxVyJWX62h).
 
@@ -40,6 +44,7 @@ All supported and tested Charge Controllers can be found [here](https://github.c
 - [Publishing data to PVOutput](https://github.com/enwi/RNGBridgeDoc/blob/main/pvoutput.md)
 - [Automatically control load output and `Out1`, `Out2` and `Out3`](https://github.com/enwi/RNGBridgeDoc/blob/main/control.md)
 - [Control `Load`, `Out1`, `Out2` and `Out3` through REST api](https://github.com/enwi/RNGBridgeDoc/blob/main/rest.md)
+- [Request current charge controller state](https://github.com/enwi/RNGBridgeDoc/blob/main/rest.md)
 
 ## About
 See the about section [here](https://github.com/enwi/RNGBridgeDoc/blob/main/about.md)
diff --git a/images/gif/mqtt.gif b/images/gif/mqtt.gif
diff --git a/mqtt.md b/mqtt.md
@@ -1,19 +1,23 @@
 # MQTT
 `RNGBridge` can publish the data read from your Charge Controller to a local MQTT Broker, thus making it accessible to other devices or home automation systems.
 It supports credentials so you can also connect to secured MQTT Brokers.
+Since ([V2.7.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.7.0)) `RNGBridge` can also automatically integrate itself into Homeassistant using [Homeassistant Discovery](https://www.home-assistant.io/docs/mqtt/discovery/).
 
 ## Setup
 1. Open the settings menu by clicking the gear icon in the top right of the page.
 2. Click on the panel named `MQTT`.
 3. Enable `MQTT`.
 4. Enter the MQTT Broker IP e.g. `192.168.2.2` in the `Server` field.
-5. Optionally enter the MQTT Broker port e.g. `1883` in the `Port` field (default is 1883 so if you are using the same port you can skip this step).
+5. Optionally enter the MQTT Broker port e.g. `1883` in the `Port` field (default is `1883` so if you are using the same port you can skip this step).
 6. Optionally enter the MQTT client identifier used by `RNGBridge` in the `Id` field.
 7. Optionally enter the MQTT Broker username in the `User` field.
 8. Optionally enter the MQTT Broker password in the `Password` field.
-9. Enter the MQTT Topic where `RNGBridge` should publish the data e.g `/solar/rng` (default is `/rng`).
-10. If you verified your settings press the `SAVE MQTT CONFIG` button.
-11. `RNGBridge` will reboot and try to connect to the MQTT Broker and displays the status on the settings page.
+9. Enter the MQTT base topic where `RNGBridge` should publish the data e.g `/solar/rng` (default is `/rng`).
+10. Optionally enter the MQTT update interval in seconds in the `Update interval (seconds)` field.
+11. Optionally enable Homeassistant Discovery and control `RNGBridge` directly through Homeassistant.
+12. Optionally enter the Homeassistant Discovery Topic in the field `Discovery Topic` (default is `homeassistant`, which is also the default of the [MQTT Integration](https://www.home-assistant.io/integrations/mqtt/)).
+13. If you verified your settings press the `SAVE MQTT CONFIG` button.
+14. `RNGBridge` will reboot and try to connect to the MQTT Broker and displays the status on the settings page.
 
 > Note that due to the limited resources of the ESP8266 only Brokers without TLS/SSL are supported for now
 
@@ -27,59 +31,64 @@ It supports credentials so you can also connect to secured MQTT Brokers.
 - If you still have issues get help on my discord server by clicking on this icon -> [![Discord](https://img.shields.io/discord/781219798931603527.svg?label=enwi&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://discord.gg/YxVyJWX62h)
 
 ## Data Structure
-The current Charge Controller data is sent every 2 seconds and is provided as a JSON object as follows:
-```
+The current Charge Controller data is sent at the configured interval and is published under the subtopic `/state` as a JSON object as follows:
+```json
 {
- "device" : "0123456789AB",
- "b" :
- {
- "charge" : 100,
- "voltage" : 13.5,
- "current" : 1.45,
- "temperature" : 25.0
- },
- "l" :
- {
- "voltage" : 13.5,
- "current" : 1.56,
- "power" : 21
- },
- "p" :
- {
- "voltage" : 32.6,
- "current" : 5.45,
- "power" : 177
- },
- "s" :
- {
- "state" : 2,
- "errorState" : 0,
- "temperature" : 25.5
- }
+ "b": {
+ "ch": 100,
+ "vo": 13.5,
+ "cu": 1.45,
+ "te": 25.0
+ },
+ "l": {
+ "vo": 13.5,
+ "cu": 1.56,
+ "po": 21
+ },
+ "p": {
+ "vo": 32.6,
+ "cu": 5.45,
+ "po": 177
+ },
+ "c": {
+ "st": 2,
+ "er": 0,
+ "te": 25.5
+ },
+ "o": {
+ "l": true,
+ "o1": false,
+ "o2": true,
+ "o3": false
+ }
 }
 ```
 
 ### Data values
 | Object/Variable | Type | Value | Description |
 |:----------------|--------|-------------------|----------------------------------------------|
-| device | String | e.g. 0123456789AB | Device identifier, MAC address of ESP |
 | b | Object | - | JSON object containing battery data |
-| charge | Number | 0 - 100 | Battery charge in % |
-| voltage | Float | 0.0 - XX.X | Battery voltage in Volts |
-| current | Float | 0.0 - XX.X | Battery current in Ampere |
-| temperature | Float | 0.0 - XX.X | Battery temperature in degrees C |
+| ch  | Number | 0 - 100 | Battery charge in % |
+| vo  | Float | 0.0 - XX.X | Battery voltage in Volts |
+| cu  | Float | 0.0 - XX.X | Battery current in Ampere |
+| te  | Float | 0.0 - XX.X | Battery temperature in degrees C |
 | l | Object | - | JSON object containing load data |
-| voltage | Float | 0.0 - XX.X | Load voltage in Volts |
-| current | Float | 0.0 - XX.X | Load current in Ampere |
-| power | Number | 0 - XXXX | Load power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
+| vo  | Float | 0.0 - XX.X | Load voltage in Volts |
+| cu  | Float | 0.0 - XX.X | Load current in Ampere |
+| po  | Number | 0 - XXXX | Load power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
 | p | Object | - | JSON object containing solar panel data |
-| voltage | Float | 0.0 - XX.X | Solar panel voltage in Volts |
-| current | Float | 0.0 - XX.X | Solar panel current in Ampere |
-| power | Number | 0 - XXXX | Solar panel power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
-| s | Object | - | JSON object containing controller state data |
-| state | Number | 0 - 6 | Charge controller state, mode of operation |
-| errorState | Number | 0 - 33488896 | Charge controller error state |
-| temperature | Float | 0.0 - XX.X | Charge controller temperature in degrees C |
+| vo | Float | 0.0 - XX.X | Solar panel voltage in Volts |
+| cu | Float | 0.0 - XX.X | Solar panel current in Ampere |
+| po | Number | 0 - XXXX | Solar panel power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
+| c | Object | - | JSON object containing controller state data |
+| st | Number | 0 - 6 | Charge controller state, mode of operation |
+| er | Number | 0 - 33488896 | Charge controller error state |
+| te | Float | 0.0 - XX.X | Charge controller temperature in degrees C |
+| o | Object | - | JSON object containing output states |
+| l | Bool | true/false | Charge controller load output enabled(true) or disabled(false) |
+| o1 | Bool | true/false | RNGBridge `Out1` enabled(true) or disabled(false) |
+| o2 | Bool | true/false | RNGBridge `Out2` enabled(true) or disabled(false) |
+| o3 | Bool | true/false | RNGBridge `Out3` enabled(true) or disabled(false) |
 
 #### state values
 - 0: charging deactivated
@@ -112,20 +121,24 @@ The current Charge Controller data is sent every 2 seconds and is provided as a
 BXX indicates the bit of the number
 
 ## Other messages
-On connection to the MQTT Broker `RNGBridge` will send a connection message which indicates that the device is online. This message is being retained as long as the connection to the Broker stays alive. If `RNGBridge` is being disconnected due to different reasons the broker will send a last will message. This disconnect message is also being retained. So whenever another client subscribes to the topic it will be notified on whether `RNGBridge` is online or offline.
+On connection to the MQTT Broker `RNGBridge` will send a connection message to the subtopic `/lwt` which indicates that the device is online.
+This message is being retained as long as the connection to the Broker stays alive.
+If `RNGBridge` is being disconnected due to different reasons the broker will send a last will message.
+This disconnect message is also being retained.
+So whenever another client subscribes to the topic it will be notified on whether `RNGBridge` is online or offline.
 
 ### Connect message
 ```
-{
- "device" : "0123456789AB",
- "connected" : true
-}
+Connected
 ```
 
 ### Disconnect message
 ```
-{
- "device" : "0123456789AB",
- "connected" : false
-}
+Disconnected
 ```
+
+## Controlling `Load`, `Out1`, `Out2` and `Out3`
+Since ([V2.7.0](https://github.com/enwi/RNGBridgeDoc/releases/tag/2.7.0)) it is possible to control the outputs of RNGBridge with MQTT.
+To turn a specific output on or off you can publish a message containing either `true` or `false` to the subtopics `/ol`, `/o1`, `/o2` and `/o3`,
+of the MQTT base topic configured in step 9.
+So with the default MQTT base topic being `/rng`, you would need to publish a message to `/rng/ol`, `/rng/o1`, `/rng/o2` and `/rng/o1`.
diff --git a/rest.md b/rest.md
@@ -1,6 +1,8 @@
 # REST API
-With the REST API you can control the `Load` output as well as the three control outputs `Out1`, `Out2` and `Out3`.
-For that you have to send a `POST`, `PUT` or `PATCH` request to the endpoint `/api/control` containing a json body with the desired state.
+With the REST API you can control the outputs as well as request the current state of the charge controller and the outputs.
+
+## Control outputs `Load`, `Out1`, `Out2` and `Out3`
+For controlling the outputs you have to send a `POST`, `PUT` or `PATCH` request to the endpoint `/api/control` containing a JSON body with the desired state.
 To turn the load output on the body needs to contain `{"load":true}`, to turn it off `{"load":false}`.
 For the three control outputs this is done in a similar manner.
 To turn on `Out1` the body needs to contain `{"out1":true}`, to turn it off `{"out1":false}`.
@@ -19,3 +21,105 @@ curl -X POST -H "Content-Type: application/json" -d '{"load":true,"out2":true,"o
 
 > Note if you have setup automatic control of the load output, out1, out2 or out3 you might be able to change the state of the output using the REST interface, but it will probably be overwritten by the automatic control in the next update cycle.
 > So make sure that automatic control is disabled if you want to use this feature.
+
+## Requesting controller state
+For getting the state of the charge controller you have to send a `GET` request to the endpoint `/api/state`.
+`RNGBridge` will then return a current state JSON object similar to the one returned with [MQTT](https://github.com/enwi/RNGBridgeDoc/blob/main/mqtt.md).
+If wanted the MQTT obect could be extended to also have these values included.
+
+### Data Structure
+```json
+{
+ "mqttsta": "Connected",
+ "otasta": "2.7.0",
+ "pvosta": "Disabled",
+ "b": {
+ "ch": 79,
+ "vo": 12.11761,
+ "cu": 8.252449,
+ "te": 18
+ },
+ "l": {
+ "vo": 12.11761,
+ "cu": 0
+ },
+ "p": {
+ "vo": 13.9,
+ "cu": 7.194245
+ },
+ "c": {
+ "st": 1,
+ "er": 0,
+ "te": 19
+ },
+ "o": {
+ "l": false,
+ "o1": false,
+ "o2": false,
+ "o3": false
+ },
+ "up": 80,
+ "he": 38008
+}
+```
+
+### Data values
+| Object/Variable | Type | Value | Description |
+|:----------------|--------|-------------------|----------------------------------------------|
+| b | Object | - | JSON object containing battery data |
+| ch | Number | 0 - 100 | Battery charge in % |
+| vo | Float | 0.0 - XX.X | Battery voltage in Volts |
+| cu | Float | 0.0 - XX.X | Battery current in Ampere |
+| te | Float | 0.0 - XX.X | Battery temperature in degrees C |
+| l | Object | - | JSON object containing load data |
+| vo | Float | 0.0 - XX.X | Load voltage in Volts |
+| cu | Float | 0.0 - XX.X | Load current in Ampere |
+| po | Number | 0 - XXXX | Load power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
+| p | Object | - | JSON object containing solar panel data |
+| vo | Float | 0.0 - XX.X | Solar panel voltage in Volts |
+| cu | Float | 0.0 - XX.X | Solar panel current in Ampere |
+| po | Number | 0 - XXXX | Solar panel power in Watts, note multiplying voltage with current gives you a more accurate value as this is the value returned by the charge controller |
+| c | Object | - | JSON object containing controller state data |
+| st | Number | 0 - 6 | Charge controller state, mode of operation |
+| er | Number | 0 - 33488896 | Charge controller error state |
+| te | Float | 0.0 - XX.X | Charge controller temperature in degrees C |
+| o | Object | - | JSON object containing output states |
+| l | Bool | true/false | Charge controller load output enabled(true) or disabled(false) |
+| o1 | Bool | true/false | RNGBridge `Out1` enabled(true) or disabled(false) |
+| o2 | Bool | true/false | RNGBridge `Out2` enabled(true) or disabled(false) |
+| o3 | Bool | true/false | RNGBridge `Out3` enabled(true) or disabled(false) |
+| mqttsta | Bool | String | Current human readable state of the MQTT module of `RNGBridge` |
+| otasta | Bool | String | Latest available version number of `RNGBridge`, only present if a software update is available |
+| pvosta | Bool | String | Current human readable state of the PVOutput module of `RNGBridge` |
+| up | Bool | Number | Uptime in seconds |
+| he | Bool | Number | Current heap usage in bytes |
+
+#### state values
+- 0: charging deactivated
+- 1: charging activated
+- 2: mppt charging mode
+- 3: equalizing charging mode
+- 4: boost charging mode
+- 5: floating charging mode
+- 6: current limiting (overpower)
+
+#### errorState values
+- B31: Reserved
+- B30: Charge MOS short circuit
+- B29: Anti-reverse MOS short circuit
+- B28: Solar panel reversly connected
+- B27: Solar panel working point over-voltage
+- B26: Solar panel counter current
+- B25: Photovoltaic input side over voltage
+- B24: Photovoltaic input side short circuit
+- B23: Photovoltaic input overpower
+- B22: Ambient temperature too high
+- B21: Controller temperature too high
+- B20: Load overpower or load over-current
+- B19: Load short circuit
+- B18: Battery under-voltage warning
+- B17: Battery over-voltage
+- B16: battery over-discharge
+- B0-B15: Reserved
+
+BXX indicates the bit of the number