wiki to repo

documentation/dashboards/nodered.md

@@ -0,0 +1,82 @@
+# Setting up PythonProtocolGateway on a RasPi with NodeRed Dashboard 2.0
+This is a simple how-to on setting up a Rasperry Pi node, attempting to be as copy/pastable as possible. As we stand on the shoulders of giants, I will refer to external how-tos for some of the steps. They did it better than I could anyway.
+
+## Requirements
+- a multicore raspberry pi. Though you can run it on a classic raspi 2/pi zero w, a pi zero 2 is the minimum for stablility.
+- a recent version of raspberry pi os.
+
+## Install Raspberry Pi OS
+[Just like it says on the tin](https://www.raspberrypi.com/documentation/computers/getting-started.html#install-an-operating-system). Throughout this, I will use some conventions assuming you used the hostname Solar, the username is Solar, and the password is SolarPowered. The rest of this doc assumes you are SSHed in using PuTTY (for windows users) or a terminal of your choice (for the rest of us heathens). The hostname will be `solar.local`, username `solar`, and password `SolarPowered`
+
+## install dependencies
+`sudo apt update && sudo apt upgrade && sudo apt install tmux git mosquitto nginx`
+
+## Configure Mosquitto MQTT server
+Using your favorite text editor, add these lines to `/etc/mosquitto/mosquitto.conf`
+
+```
+listener 1883
+
+allow_anonymous false 
+password_file /etc/mosquitto/passwd
+
+```
+Create a new `mosquitto` password file while adding an mqtt user `sudo mosquitto_passwd -c /etc/mosquitto/passwd solar` - to add another user later, drop the `-c`. Start the service with `sudo systemctl start mosquitto`, set the service to start on boot with `sudo systemctl enable mosquitto`. 
+
+## Download/configure PythonProtocolGateway
+### Download 
+`mkdir ~/src/ && cd ~/src && git clone https://github.com/HotNoob/PythonProtocolGateway.git` 
+### Configure
+[Follow the wiki](https://github.com/HotNoob/PythonProtocolGateway/wiki)
+
+## Install/configure NodeRed service
+### Install
+[Install how-to](https://nodered.org/docs/getting-started/raspberrypi) - As of the 6 August 2024, you can just paste in `bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)`
+
+## install NodeRed Nodes
+1. [Log in.](http://solar.local:1880/)
+2. Click the hambuger menu. 
+3. Go to `Manage palette`. 
+4. Under the `Install` tab, search for `@flowfuse/node-red-dashboard`. Click `Install`.
+5. Optional: Under the `Install` tab, search for `node-red-contrib-influxdb`, click `Install`.
+
+## Optional: Install/Enable InfluxDB
+If you want to do some historical logging, InfluxDB is a better solution than the node-red internal db.
+1. Install influx `sudo apt install influxdb influxdb-client && sudo systemctl enable influxdb && sudo systemctl start  `
+2. Create the `solar` db in influx `echo "CREATE DATABASE solar" | influx`
+3. Drag an `InfluxDB Out Node` out into the workspace, connect a wire from the `mqtt in` node to the `InfluxDB Out` node. Double click the node, click the `+`, give it a name and the name of the database from above (solar). Click add. It will return you to the node setup, where you will give it a name and a measurement (`solar` in my setup), click `save` or `done`.
+
+### TODO: create some nodes that consume the DB info.
+
+## Create your flow or import the example flow (for EG4 users)
+### Import example
+Go to the hamburger, down to `Import`, click `select a file to import`, find `nodered-example-flow.json` in the repo. You should be left with something like this.
+![example flow](https://github.com/user-attachments/assets/c2c284f8-e40f-4e05-bcb7-e054e32dad4c)
+
+### Create your own flow
+1. Drag a `debug` node out - we will be using this throughout to see how the data flows. You can see the debug output by dragging a wire from an output to the debug's input and turning it on.
+2. Drag an `mqtt in` node out to the workspace. click the pencil to create a new mqtt-broker-node. Give it a name, enter the hostname in the server field (`solar.local` in our example), click security, add the username and password, click `add` orf `update`. Under `Topic`, enter `home/inverter`. Click done.
+3. Drag a json node out onto the workspace, connect the input (left) side of the `json` node to the output of the `mqtt in` node.
+4. For each of the things you want on the dashboard, add in a `function` node. This is to filter out the thing you want displayed, in this example, battery percentage. Drag a wire from the `json` node to the function you just created.
+```
+msg.payload = parseInt(msg.payload.battery_percentage);
+return  msg;
+```
+click done.
+4. From here on out, you will be setting up the wigets you want to see. Checkout the [flowfuse dashboard wiki](https://dashboard.flowfuse.com/getting-started.html) for more info.  For each of the functions you just created, create a `chart`, `gauge`, or `text` node to display the things the way you want them displayed. You will need to create a group and page node on the first, the ui will help you throuhg that.
+
+## Edit the nginx config file to point at the dashboard
+Use sudo and your favorite editor to edit `/etc/nginx/sites-enabled/default`. jump down to the `server_name _` section and replace everything between the `{` and `}` so it's like below.
+
+```        server_name _;
+                location / {
+                include proxy_params;
+                rewrite ^/(.*) /dashboard/$1 break;
+                proxy_pass http://127.0.0.1:1880;
+        }
+``` 
+
+You should now be able to browse to [Solar.local/Home](http://solar.local/Home/)
+
+---
+source: https://github.com/yNosGR/PythonProtocolGateway/blob/NodeRed_howto/NodeRed.MD

documentation/devices/EG4.md

@@ -0,0 +1,32 @@
+## Hardware
+1. USB to RS485 Adapter (RJ45) from EG4 **or** USB to RS485 Adapter & RJ45 Ethernet cable ( or 3 wires ) 
+2. Connect RJ45 ethernet cable to an avaiable RS485/Modbus port:
+
+![image](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/c387d8af-5864-4795-9958-3161d23501f1)
+
+<details>
+  <summary>Example Image</summary>
+
+![327825986-94315fea-abad-4c9c-942d-aa5ad4b47802](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/f8bee2f2-4f7c-4fd8-a437-2f03af1ba2b0)
+
+</details>
+
+3. Connect appropriate wires to USB RS485 Adapter
+
+## Configuration
+Follow configuration example for ModBus RTU to MQTT
+https://github.com/HotNoob/PythonProtocolGateway/wiki/Configuration-Examples#modbus-rtu-to-mqtt
+
+#### EG4 6000XP, EG4 18Kpv
+```
+protocol_version = eg4_v58
+baud = 19200
+```
+
+#### EG4 3000EHV inverters
+```
+protocol_version = eg4_3000ehv_v1
+```
+
+protocols may not be limited to the models listed.
+

documentation/devices/Growatt.md

@@ -0,0 +1,120 @@
+## Hardware
+1. USB-B or USB-A cable
+2. for models with a DB9 port a DB9 RS232 adapter is required. "Before use RS232 communication, you should make sure the follow PIN1 and PIN2 are OFF"
+3. Connect cable to wifi dongle port; if a alternative usb port exists, try connecting to that one first. 
+
+## Configuration
+Follow configuration example for ModBus RTU to MQTT
+https://github.com/HotNoob/PythonProtocolGateway/wiki/Configuration-Examples#modbus-rtu-to-mqtt
+
+```
+protocol_version = v0.14
+```
+
+## HomeAssistant Cards
+Here are some example cards. If you want to use them, you will have to change the variable names and others to reflect your configs. 
+
+## PV1 & PV2 Card
+![pv watts](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/372980f9-f2d6-48e5-9acd-ee519badb61f)
+<details>
+  <summary>code</summary>
+
+```
+type: horizontal-stack
+cards:
+  - type: gauge
+    needle: false
+    name: PV1 Voltage
+    entity: sensor.growatt_inverter_pv1_voltage
+    severity:
+      green: 150
+      yellow: 50
+      red: 0
+  - type: gauge
+    entity: sensor.growatt_inverter_pv2_voltage
+    name: PV2 Voltage
+    severity:
+      green: 125
+      yellow: 50
+      red: 0
+  - type: gauge
+    needle: false
+    entity: sensor.growatt_inverter_pv1_watts
+    name: PV1 Watts
+    severity:
+      green: 750
+      yellow: 250
+      red: 0
+  - type: gauge
+    entity: sensor.growatt_inverter_pv2_watts
+    name: PV2 Watts
+    severity:
+      green: 750
+      yellow: 250
+      red: 0
+```
+</details>
+
+## Output Card
+![output](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/9a129dad-73bc-4401-9746-d7a0dd22cf0a)
+<details>
+  <summary>code</summary>
+
+```
+type: horizontal-stack
+cards:
+  - type: gauge
+    needle: true
+    entity: sensor.growatt_inverter_output_voltage
+    name: Output Voltage
+    max: 270
+    min: 210
+    segments:
+      - from: 0
+        color: '#db4437'
+      - from: 220
+        color: '#ffa600'
+      - from: 235
+        color: '#43a047'
+      - from: 245
+        color: '#ffa600'
+      - from: 250
+        color: '#db4437'
+  - type: gauge
+    entity: sensor.growatt_inverter_output_hz
+    name: Output Hertz
+    unit: hz
+    needle: true
+    max: 62
+    min: 58
+    segments:
+      - from: 0
+        color: '#db4437'
+      - from: 59
+        color: '#ffa600'
+      - from: 59.5
+        color: '#43a047'
+      - from: 60.5
+        color: '#ffa600'
+      - from: 61
+        color: '#db4437'
+  - type: gauge
+    needle: false
+    entity: sensor.growatt_inverter_output_wattage
+    name: Output Watts
+    severity:
+      green: 0
+      yellow: 1200
+      red: 8000
+    max: 12000
+  - type: gauge
+    entity: sensor.growatt_inverter_output_current
+    name: Output Current
+    severity:
+      green: 0
+      yellow: 10
+      red: 40
+    max: 50
+
+```
+</details>

documentation/devices/SOK.md

@@ -0,0 +1,16 @@
+```
+transport=modbus_rtu
+protocol_version=pace_bms_v1.3
+```
+The Battery's RS485 Protocol must be set to: `PACE_MODBUS` 
+
+Plugs into the RS485A port
+
+This protocol is only able to read the battery that is directly connected to it; a modbus hub can be used to help fix this limitation. 
+
+SOK, jakiper 48v100AH battery and other PACE BMS batteries.
+
+![pace-bms](https://github.com/HotNoob/InverterModBusToMQTT/assets/2180145/1ea28956-5d74-4bdb-9732-341d492d15c3)
+
+### rs485a pinout ### 
+Pin 1,2,3 or Pin 8,7,6

documentation/devices/Sigineer.md

@@ -0,0 +1,45 @@
+## Hardware
+1. USB-B or USB-A cable
+2. Connect usb cable.
+
+## Configuration
+Follow configuration example for ModBus RTU to MQTT
+https://github.com/HotNoob/PythonProtocolGateway/wiki/Configuration-Examples#modbus-rtu-to-mqtt
+
+```
+protocol_version = sigineer_v0.11
+```
+
+
+## Home Assistant Cards
+
+### Voltage Card
+![sigineer output](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/55900744-6aaf-4b44-bf3e-46976fdffce2)
+
+<details>
+<summary>code</summary>
+
+```
+type: horizontal-stack
+cards:
+  - type: gauge
+    needle: false
+    name: Battery
+    entity: sensor.sigineer_battery_voltage
+  - type: gauge
+    entity: sensor.sigineer_output_voltage
+    name: Output
+  - type: gauge
+    needle: false
+    entity: sensor.sigineer_bus_voltage
+    name: Bus
+  - type: gauge
+    entity: sensor.sigineer_grid_voltage
+    name: Grid
+    severity:
+      green: 750
+      yellow: 250
+      red: 0
+
+```
+</details>

documentation/devices/SolArk.md

@@ -0,0 +1,17 @@
+Currently untested / unconfirmed. ppg version 1.1.3 and higher
+
+## Hardware
+1. USB to RS485 Adapter & RJ45 Ethernet cable ( or 3 wires ) 
+2. Connect RJ45 ethernet cable to an available RS485/Modbus port:
+3. Connect appropriate wires to USB RS485 Adapter. see sol ark documentation
+
+![image](https://github.com/HotNoob/PythonProtocolGateway/assets/2180145/1d14a542-25ab-4233-917b-304c5bfe2ef2)
+
+
+## Configuration
+Follow configuration example for ModBus RTU to MQTT
+https://github.com/HotNoob/PythonProtocolGateway/wiki/Configuration-Examples#modbus-rtu-to-mqtt
+
+```
+protocol_version = solark_v1.1
+```

documentation/usage/configuration_examples/modbus_rtu_to_modbus_tcp.md

@@ -0,0 +1,44 @@
+### ModBus RTU to ModBus TCP
+untested; in dev
+```
+[general]
+log_level = DEBUG
+
+[transport.0] #name must be unique, ie: transport.modbus
+#rs485 / modbus device
+#protocol config files are located in protocols/
+protocol_version = v0.14
+analyze_protocol = false
+write = false
+
+#modbus address
+address = 1
+port = {{serial port, likely /dev/ttyUSB0}}
+baudrate = 9600
+
+#modbus tcp/tls/udp example
+#host = 192.168.0.7
+#port = 502
+#override protocol reader
+#transport = modbus_tcp
+
+#the 'transport' that we want to share this with
+bridge = transport.1
+
+manufacturer = {{Your device's manufacturer here}}
+model = {{Your device's model number here}}
+#optional; leave blank to autofetch serial from device
+serial_number = 
+
+read_interval = 10
+error_interval = 60
+
+
+[transport.1]
+#modbus tcp
+protocol_version = v0.14
+transport=modbus_tcp
+write = true
+host = 127.0.0.1
+port = 502
+```