Updated Smart Meter Interface (markdown)

Smart-Meter-Interface.md

@@ -20,45 +20,68 @@ The driver reverts to the default `#define` definition if no `>M` section is fou
   
 ## Descriptor Syntax
 
+### Meter Declaration
 Define an `>M` section with the number of meters to be connected (up to 5) - e.g. `>M 3`
 
+Syntax
+`+<M>,<rxGPIO>,<type>,<flag>,<parameter>,<jsonPrefix>{,<txGPIO>,<txPeriod>,<cmdTelegram>}`  
 
-Definitions are according to the type of interface for each meter.  
+- `M` - meter number  
+- `rxGPIO` - meter data receive GPIO  
+- `type` - meter type of meter  
+  - `o`=obis ASCII type of coding  
+  - `s`=sml binary smart message coding  
+  - `c`=counter type  
+  - `e`=ebus binary coding  
+  - `m`=modbus binary coding  
+  - `p`=PZEM  
+  - `r`=raw binary coding (any binary telegram)  
+- `flag` - counter flag  
+  - 0=without pullup  
+  - 1=with pullup   
+- `parameter` - parameters according to meter type  
+  - for `o,s,e,m,r`: serial baud rate  
+  - for `c`:  
+    - positive value = counter poll interval  
+    - negative value = debounce time (milliseconds)for irq driven counters  
+- `jsonPrefix` - prefix for Web UI and MQTT JSON payload. Up to 7 characters  
+- `txGPIO` - meter command transmit GPIO  
+- `txPeriod` - number of 250ms increments. Period to repeat the transmission of commands to the meter  
+- `cmdTelegram` - comma separated hex coded byte blocks to send to meter device. For modbus each block is a command to retrieve a certain register from the meter  
 
-`+1,3,o,0,9600,OBIS`
+Examples:  
+`+1,3,o,0,9600,OBIS`  
+`+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010`  
 
-- `+1` adds the meter number 1
-- the source GPIO pin of signal => here 3 => RX pin
-- the type of meter => `o`=obis ASCII type of coding, `s`=sml binary smart message coding, `c`=counter type, `e`=ebus binary coding, `m`=modbus binary coding,`r`=raw binary coding (any binary telegram).
-- flag => 0=counter without pullup, 1=with pullup 
-- parameter => on `o,s,e,m,r` type serial baud rate, on type `c` positive value means counter poll interval, negative value irq driven counters with this debounce time (milliseconds)
-- MQTT JSON prefix up to 7 chars,this prefix is also shown in WEBUI
-- in case of interactive telegram comma separated 
-
-`+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010`
-- GPIO pin of transmit signal
-- timeframe in 250 ms steps
-- comma separated hex coded byte blocks to send to meter device, every n*250 ms, in case of modbus each block is a command to retrieve a certain register of the meter
-
-the list of meter entries start with the meter number to which this decoder belongs. (up to 16 entries, #define MAX_VARS 16)
+### Meter Metrics
+Each meter typically provides multiple metrics (voltage, power, humidity, etc.) which it measures. You must provide entries (up to 16, #define MAX_VARS 16) to define how to decode the data and put it into your variables. These entries start with the meter number to which this decoder belongs.
 
 `1,1-0:1.8.0*255(@1,consumption,KWh,Total_in,4`
 
-- meter number, comma separated  
-- then until `@` char => sequence to decode OBIS as ASCII, or SML, EBUS, RAW as HEX ASCII  
-  - OBIS: ascii OBIS code until the `(` char which indicates the start of the meter value  
-  - SML: SML binary OBIS as hex until FF indicating start of SML coded value  
-  - EBUS,RAW: hex values of EBUS,RAW block to compare  `xx` means ignore value, `ss` = extract this signed byte, `uu` = extract this unsigned byte, `uuuu` = extract this unsigned word, `ssss` = extract this signed word, `ffffffff` = extract this float value.  
-    - decoding a bit as 0,1 is done after the `@` sign with `bx:` x=0..7 extracting the corresponding bit from a byte.  
-      e.g., 1,xxxx5017xxuu@b0:1,Solarpump,,Solarpump,0 extracts bit zero  
-    - in the case of modbus, `ix` designates the index x (0..n) referring to the demanded block in the transmit section of the meter definition.
+- Meter number  
+- Data decoding specification. Decode OBIS as ASCII; SML, EBUS, RAW as HEX ASCII
+  - OBIS: ascii OBIS code terminated with `(` character which indicates the start of the meter value  
+  - SML: SML binary OBIS as hex terminated with `0xFF` indicating start of SML encoded value  
+  - EBUS,RAW: hex values of EBUS,RAW block to compare  
+    - `xx` means ignore value  
+    - `ss` = extract this signed byte  
+    - `uu` = extract this unsigned byte  
+    - `uuuu` = extract this unsigned word  
+    - `ssss` = extract this signed word  
+    - `ffffffff` = extract this float value  
+    - decoding a 0/1 bit is indicated by a `@` character followed by `bx:` x=0..7 extracting the corresponding bit from a byte.  
+      e.g., 1,xxxx5017xxuu@b0:1,Solarpumpe,,Solarpump,0 extracts bit zero  
+    - in the case of modbus, `ix:` designates the index x=0..n referring to the requested block in the transmit section of the meter definition
       e.g., 1,010404ffffffffxxxx@i0:1,Voltage P1,V,Voltage_P1,2  
-- scaling factor (divisor) (may also be negative or smaller then zero e.g. 0.1 => result * 10)  
-  when decoding a string result (e.g., a serial meter) put a `#` character here (only in one line per meter). For OBIS, you need a `)` termination character after the `#` character  
-- name of signal in WEBUI (max 23 chars)  
-- unit of signal (max 7 chars)  
-- name of MQTT signal (max 23 chars)  
-- number of decimals (decimal precision). Add 16 to transmit the data immediately. Otherwise it is transmitted on [`TelePeriod`](Commands#teleperiod)  
+- `@` decoding definition termination character  
+- scaling factor (divisor)  
+  This can be a fraction (e.g., 0.1 => result * 10), or a negative value  
+  When decoding a string result (e.g., a serial meter), use `#` character for this parameter (only in one line per meter). For OBIS, you need a `)` termination character after the `#` character  
+- Web UI label (max 23 chars)  
+- Unit of measure (max 7 chars)  
+- MQTT variable name (max 23 chars)  
+- Number of decimals (decimal precision)  
+  Add 16 to transmit the data immediately. Otherwise it is transmitted on [`TelePeriod`](Commands#teleperiod)  
 
 `#` character terminates the list  
 
@@ -66,11 +89,11 @@ the list of meter entries start with the meter number to which this decoder belo
 
 with the '=' char at the beginning of a line you may do some special decoding  
 
-- `=m` does math  `+,-,*,/` a `#` before a number designates a constant number  
+- `=m` perform arithmetic (`+,-,*,/`) on the metric. Use `#` before a number to designate a constant value  
   example:  
-  `=m 3+4+5/#3`  add result of decoder entry 3,4,5 and divided by 3 (average)  
-- `=d` difference calculated time difference within a decoder entry  
+  `=m 3+4+5/#3` add result of decoder entry 3,4,5 and divided by 3 (i.e., average)  
+- `=d` difference calculated between metric values decoded at time interval  
   example:  
-  `=d 3 10`  calculate difference of decoder entry 3 after 10 seconds each.  
+  `=d 3 10` calculate 10 second interval difference of decoder entry 3  
 - `=h` html text (up to 30 chars)  
   inserts a html line between entries (these lines do not count as decoder entry)