diff --git a/Smart-Meter-Interface.md b/Smart-Meter-Interface.md index 0b9a3c73..b62bd305 100644 --- a/Smart-Meter-Interface.md +++ b/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 +`+,,,,,{,,,}` -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) \ No newline at end of file