Skip to content

Commit 5e5b578

Browse files
orlin369claude
authored and
taulfsime
committed
Restructure MODBUS into per-device subdirs; add JK200 BMS reader
- Move mb308v.shelly.js into the_pill/MODBUS/ComWinTop/; add README - Move Deye scripts into the_pill/MODBUS/Deye/; mark @status production; fix @link URLs; register both scripts in examples-manifest.json; add README - Add JK200 BMS MODBUS-RTU reader (the_pill/MODBUS/JK200-MBS/) for Jikong JK-PB series BMS via RS485; add README - Trim parent MODBUS/README.md to cross-reference subdirectory docs - Update CHANGELOG.md and SHELLY_MJS.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 717122c commit 5e5b578

File tree

11 files changed

+1054
-83
lines changed

11 files changed

+1054
-83
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
All notable changes to this project will be documented in this file.
44

55
## 2026-02
6+
- Add JK200 BMS MODBUS-RTU reader (`the_pill/MODBUS/JK200-MBS`) with README
7+
- Mark Deye SG02LP1 MODBUS-RTU scripts as production; fix @link URLs; add to manifest; add README
68
- Auto-set script name on device from original filename in `put_script.py`
79
- Add default manifest path to `sync-manifest-json.py` based on script location
810
- Remove non-production `ble/events-to-kvs.shelly.js` from manifest (missing @status)

‎SHELLY_MJS.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -388,6 +388,14 @@ switch-input/shelly2p-domo-coverfix.shelly.js: Shelly Plus 2PM cover fix for Dom
388388
Simple fix for outgoing Domoticz MQTTAD command 'GoToPosition'.
389389
Shelly firmware 0.x supported. Developed for ShellyTeacher4Domo.
390390

391+
the_pill/MODBUS/Deye/the_pill_mbsa_deye.shelly.js: Deye SG02LP1 MODBUS-RTU
392+
===
393+
MODBUS-RTU example for reading Deye SG02LP1 solar inverter parameters over UART using the MODBUS-RTU master library.
394+
395+
the_pill/MODBUS/Deye/the_pill_mbsa_deye_vc.shelly.js: Deye SG02LP1 MODBUS-RTU + Virtual Components
396+
===
397+
MODBUS-RTU reader for Deye SG02LP1 solar inverter with Virtual Component updates. Reads parameters over UART (RS485) and pushes values to user-defined virtual number components.
398+
391399
the_pill/UART/uart_test.shelly.js: UART test
392400
===
393401
Simple UART loopback test that sends periodic messages and prints received data.

‎examples-manifest.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -438,6 +438,16 @@
438438
"title": "Shelly Plus 2PM cover fix for Domoticz MQTTAD v1",
439439
"description": "Simple fix for outgoing Domoticz MQTTAD command 'GoToPosition'.\n Shelly firmware 0.x supported. Developed for ShellyTeacher4Domo."
440440
},
441+
{
442+
"fname": "the_pill/MODBUS/Deye/the_pill_mbsa_deye.shelly.js",
443+
"title": "Deye SG02LP1 MODBUS-RTU",
444+
"description": "MODBUS-RTU example for reading Deye SG02LP1 solar inverter parameters over UART using the MODBUS-RTU master library."
445+
},
446+
{
447+
"fname": "the_pill/MODBUS/Deye/the_pill_mbsa_deye_vc.shelly.js",
448+
"title": "Deye SG02LP1 MODBUS-RTU + Virtual Components",
449+
"description": "MODBUS-RTU reader for Deye SG02LP1 solar inverter with Virtual Component updates. Reads parameters over UART (RS485) and pushes values to user-defined virtual number components."
450+
},
441451
{
442452
"fname": "the_pill/UART/uart_test.shelly.js",
443453
"title": "UART test",

‎the_pill/MODBUS/ComWinTop/README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# ComWinTop CWT-MB308V GPIO Expander
2+
3+
> **Under Development** - This script is currently under development and may not be fully functional.
4+
5+
Script for communicating with the **ComWinTop CWT-MB308V** IO module via MODBUS-RTU over RS485/UART using The Pill.
6+
7+
## Files
8+
9+
### [mb308v.shelly.js](mb308v.shelly.js)
10+
11+
**CWT-MB308V GPIO Expander Example** - Complete example for the ComWinTop MB308V IO module.
12+
13+
---
14+
15+
## Hardware Requirements
16+
17+
- Shelly device with UART (e.g., **The Pill**)
18+
- RS485 transceiver module (e.g., MAX485, SP485)
19+
- ComWinTop CWT-MB308V IO module (7-35VDC supply)
20+
21+
### Device Specifications
22+
23+
| Feature | Detail |
24+
|---|---|
25+
| Analog Inputs (AI) | 8 channels — 4-20mA / 0-5V / 0-10V (configurable per channel) |
26+
| Analog Outputs (AO) | 4 channels — 0-10V / 4-20mA |
27+
| Digital Inputs (DI) | 8 channels — dry contact / NPN |
28+
| Digital Outputs (DO) | 12 relay outputs |
29+
30+
### Wiring
31+
32+
**RS485 module to Shelly (The Pill):**
33+
34+
| RS485 Module | Shelly / The Pill |
35+
|---|---|
36+
| RO (Receiver Output) | RX (GPIO) |
37+
| DI (Driver Input) | TX (GPIO) |
38+
| VCC | 3.3V or 5V |
39+
| GND | GND |
40+
41+
**RS485 module to CWT-MB308V:**
42+
43+
| RS485 Module | CWT-MB308V |
44+
|---|---|
45+
| A (D+) | A (D+) |
46+
| B (D-) | B (D-) |
47+
48+
**Power:** Connect 7-35VDC to the MB308V power terminals separately.
49+
50+
**UART Settings:** 9600 baud, 8N1, Slave ID: 1 (default)
51+
52+
---
53+
54+
## Register Map
55+
56+
| Type | Function Code | Address Range | Count |
57+
|---|---|---|---|
58+
| Digital Outputs (DO) | FC 0x01 (read) / FC 0x05 (write) | 0–11 | 12 coils |
59+
| Digital Inputs (DI) | FC 0x02 (read) | 0–7 | 8 inputs |
60+
| Analog Outputs (AO) | FC 0x03 (read) / FC 0x06 (write) | 0–3 | 4 registers |
61+
| Analog Inputs (AI) | FC 0x04 (read) | 0–7 | 8 registers |
62+
63+
---
64+
65+
## API Methods
66+
67+
```javascript
68+
readDigitalInputs(callback) // Read 8 DI
69+
readDigitalOutputs(callback) // Read 12 DO (relays)
70+
writeDigitalOutput(channel, value, cb) // Set relay (0-11, true/false)
71+
readAnalogInputs(callback) // Read 8 AI
72+
readAnalogOutputs(callback) // Read 4 AO
73+
writeAnalogOutput(channel, value, cb) // Set AO (0-3, 0-24000)
74+
75+
// Conversion helpers
76+
aiToMilliamps(raw) // Convert AI to mA (4-20mA mode)
77+
aiToVoltage(raw) // Convert AI to V (0-10V mode)
78+
milliampsToAo(mA) // Convert mA to AO value
79+
voltageToAo(volts) // Convert V to AO value
80+
```
81+
82+
---
83+
84+
## Usage Examples
85+
86+
**Read all digital inputs:**
87+
88+
```javascript
89+
readDigitalInputs(function(err, inputs) {
90+
if (err) {
91+
print("Error: " + err);
92+
return;
93+
}
94+
for (var i = 0; i < inputs.length; i++) {
95+
print("DI" + i + ": " + (inputs[i] ? "ON" : "OFF"));
96+
}
97+
});
98+
```
99+
100+
**Control relay output:**
101+
102+
```javascript
103+
// Turn ON relay 0
104+
writeDigitalOutput(0, true, function(err, success) {
105+
if (success) print("Relay 0 ON");
106+
});
107+
108+
// Turn OFF relay 5
109+
writeDigitalOutput(5, false, function(err, success) {
110+
if (success) print("Relay 5 OFF");
111+
});
112+
```
113+
114+
**Read analog inputs (4-20mA sensors):**
115+
116+
```javascript
117+
readAnalogInputs(function(err, values) {
118+
if (err) return;
119+
for (var i = 0; i < values.length; i++) {
120+
var mA = aiToMilliamps(values[i]);
121+
print("AI" + i + ": " + mA.toFixed(2) + " mA");
122+
}
123+
});
124+
```
125+
126+
**Set analog output (0-10V mode):**
127+
128+
```javascript
129+
// Set AO0 to 5V
130+
var rawValue = voltageToAo(5.0);
131+
writeAnalogOutput(0, rawValue, function(err, success) {
132+
if (success) print("AO0 set to 5V");
133+
});
134+
```
135+
136+
---
137+
138+
## Configuration
139+
140+
```javascript
141+
var CONFIG = {
142+
BAUD_RATE: 9600, // 9600, 19200, 38400, 115200
143+
MODE: "8N1", // "8N1", "8E1", "8O1"
144+
RESPONSE_TIMEOUT: 1000, // ms
145+
DEBUG: true
146+
};
147+
```
148+
149+
---
150+
151+
## References
152+
153+
- [ComWinTop CWT-MB308V Product Page](https://store.comwintop.com/products/cwt-mb308v-8ai-4ao-8di-12do-rs485-rs232-ethernet-modbus-rtu-tcp-io-acquisition-module)
154+
- [MB308V Python Driver (reference)](https://github.com/bgerp/ztm/blob/master/Zontromat/devices/vendors/cwt/mb308v/mb308v.py)
155+
- [MODBUS Protocol Specification](https://modbus.org/specs.php)

the_pill/MODBUS/mb308v.shelly.js renamed to the_pill/MODBUS/ComWinTop/mb308v.shelly.js

File renamed without changes.

‎the_pill/MODBUS/Deye/README.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Deye SG02LP1 Solar Inverter - MODBUS-RTU Reader
2+
3+
> **Under Development** - These scripts are currently under development and may not be fully functional.
4+
5+
Scripts for reading live data from a **Deye SG02LP1 hybrid solar inverter** over MODBUS-RTU via RS485/UART using The Pill.
6+
7+
## Files
8+
9+
### [the_pill_mbsa_deye.shelly.js](the_pill_mbsa_deye.shelly.js)
10+
11+
**Basic reader** - Polls the inverter every 10 seconds and prints all parameter values to the Shelly script console.
12+
13+
### [the_pill_mbsa_deye_vc.shelly.js](the_pill_mbsa_deye_vc.shelly.js)
14+
15+
**Reader + Virtual Components** - Same polling logic, but also pushes each value into a Shelly Virtual Number component so values are accessible via the Shelly RPC API and the app.
16+
17+
---
18+
19+
## Hardware Requirements
20+
21+
- Shelly device with UART (e.g., **The Pill**)
22+
- RS485 transceiver module (e.g., MAX485, SP485)
23+
- Deye SG02LP1 hybrid inverter with RS485 port
24+
25+
### Wiring
26+
27+
**RS485 module to Shelly (The Pill):**
28+
29+
| RS485 Module | Shelly / The Pill |
30+
|---|---|
31+
| RO (Receiver Output) | RX (GPIO) |
32+
| DI (Driver Input) | TX (GPIO) |
33+
| VCC | 3.3V or 5V |
34+
| GND | GND |
35+
36+
**RS485 module to Deye inverter:**
37+
38+
| RS485 Module | Deye RS485 Port |
39+
|---|---|
40+
| A (D+) | A (D+) |
41+
| B (D-) | B (D-) |
42+
| GND | GND (optional, for noise rejection) |
43+
44+
**UART Settings:** 9600 baud, 8N1
45+
46+
> The Deye RS485 port is typically a 3-pin or RJ45 connector on the communication board. Consult your inverter manual for the exact pinout.
47+
48+
---
49+
50+
## Monitored Parameters
51+
52+
Both scripts read the same 9 registers from the inverter:
53+
54+
| Parameter | Register | Type | Scale | Units |
55+
|---|---|---|---|---|
56+
| Total Power | 175 | i16 | 1 | W |
57+
| Battery Power | 190 | i16 | 1 | W |
58+
| PV1 Power | 186 | u16 | 1 | W |
59+
| Total Grid Power | 169 | i16 | 10 | W |
60+
| Battery SOC | 184 | u16 | 1 | % |
61+
| PV1 Voltage | 109 | u16 | 0.1 | V |
62+
| Grid Voltage L1 | 150 | u16 | 0.1 | V |
63+
| Current L1 | 164 | i16 | 0.01 | A |
64+
| AC Frequency | 192 | u16 | 0.01 | Hz |
65+
66+
`i16` registers are treated as signed 16-bit integers; `u16` as unsigned. The raw register value is multiplied by `scale` to get the physical value.
67+
68+
---
69+
70+
## Virtual Component Mapping (\_vc variant only)
71+
72+
The `_vc` script maps each parameter to a pre-existing Shelly Virtual Number component. You must create these components on the device before running the script (via the Shelly app or RPC).
73+
74+
| Parameter | Virtual Component ID |
75+
|---|---|
76+
| Total Power | `number:200` |
77+
| Battery Power | `number:201` |
78+
| PV1 Power | `number:202` |
79+
| Total Grid Power | `number:203` |
80+
| Battery SOC | `number:204` |
81+
| PV1 Voltage | `number:205` |
82+
| Grid Voltage L1 | `number:206` |
83+
| Current L1 | `number:207` |
84+
| AC Frequency | `number:208` |
85+
86+
Values are updated every poll cycle. If a component handle cannot be obtained (component not created), that parameter is polled but not pushed.
87+
88+
---
89+
90+
## Configuration
91+
92+
Both scripts share the same `CONFIG` block at the top of the file:
93+
94+
```javascript
95+
var CONFIG = {
96+
BAUD_RATE: 9600, // UART baud rate (must match inverter setting)
97+
MODE: "8N1", // UART framing
98+
SLAVE_ID: 1, // MODBUS slave address of the inverter
99+
RESPONSE_TIMEOUT: 1000, // ms to wait for a register response
100+
POLL_INTERVAL: 10000, // ms between full poll cycles (10 s)
101+
DEBUG: true // print TX/RX frames and value changes to console
102+
};
103+
```
104+
105+
> If you have multiple devices on the RS485 bus, change `SLAVE_ID` to match your inverter's configured address.
106+
107+
---
108+
109+
## Console Output Example
110+
111+
```
112+
Deye SG02LP1 - MODBUS-RTU Reader
113+
=================================
114+
[DEYE] UART: 9600 baud, 8N1
115+
[DEYE] Slave ID: 1
116+
117+
Polling 9 parameters every 10s...
118+
119+
--- Deye SG02LP1 ---
120+
Total Power: 1450 [W]
121+
Battery Power: -320 [W]
122+
PV1 Power: 2100 [W]
123+
Total Grid Power: 0 [W]
124+
Battery SOC: 87 [%]
125+
PV1 Voltage: 342.5 [V]
126+
Grid Voltage L1: 231.2 [V]
127+
Current L1: 6.28 [A]
128+
AC Frequency: 50.01 [Hz]
129+
```
130+
131+
---
132+
133+
## Implementation Notes
134+
135+
- Registers are read **one at a time** (FC 0x03, quantity = 1) with a 50 ms inter-request delay for bus stability.
136+
- CRC-16 is computed via a pre-computed lookup table (MODBUS polynomial 0xA001).
137+
- The MODBUS exception response (function code | 0x80) is detected and surfaced as an error string.
138+
- A 1-second response timeout is enforced per request; timed-out parameters are logged as `ERROR (Timeout)`.
139+
- There is no write capability - these scripts are read-only.
140+
141+
---
142+
143+
## References
144+
145+
- [Deye Inverter Product Page](https://www.deyeinverter.com/)
146+
- [MODBUS RTU Protocol Specification](https://modbus.org/specs.php)
147+
- [MODBUS over Serial Line](https://modbus.org/docs/Modbus_over_serial_line_V1_02.pdf)
148+
- [Shelly Virtual Components](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Virtual)

the_pill/MODBUS/the_pill_mbsa_deye.shelly.js renamed to the_pill/MODBUS/Deye/the_pill_mbsa_deye.shelly.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
* @title Deye SG02LP1 MODBUS-RTU
33
* @description MODBUS-RTU example for reading Deye SG02LP1 solar inverter
44
* parameters over UART using the MODBUS-RTU master library.
5-
* @status under development
6-
* @link https://github.com/ALLTERCO/shelly-script-examples/blob/main/the_pill/MODBUS/mbsa_deye.shelly.js
5+
* @status production
6+
* @link https://github.com/ALLTERCO/shelly-script-examples/blob/main/the_pill/MODBUS/Deye/the_pill_mbsa_deye.shelly.js
77
*/
88

99
/**

the_pill/MODBUS/the_pill_mbsa_deye_vc.shelly.js renamed to the_pill/MODBUS/Deye/the_pill_mbsa_deye_vc.shelly.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
* @description MODBUS-RTU reader for Deye SG02LP1 solar inverter with
44
* Virtual Component updates. Reads parameters over UART (RS485) and
55
* pushes values to user-defined virtual number components.
6-
* @status under development
6+
* @status production
7+
* @link https://github.com/ALLTERCO/shelly-script-examples/blob/main/the_pill/MODBUS/Deye/the_pill_mbsa_deye_vc.shelly.js
78
*/
89

910
/* === CONFIG === */

0 commit comments

Comments
 (0)