mirrors
/
Tasmota
mirror of https://github.com/arendst/Tasmota.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated Smart Meter Interface (markdown)

Michael Ingraham 2019-09-07 16:47:59 -04:00
parent 73e4f2ec8f
commit 3f153fc118
1 changed files with 35 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

68
Smart-Meter-Interface.md

@ -2,33 +2,32 @@
[Smart Meter Descriptors](Smart-Meter-Interface-Descriptors) [Smart Meter Descriptors](Smart-Meter-Interface-Descriptors)
**The following types of meter protocols are supported:** To use this interface, connect the meter to available device GPIO pins. These GPIO must be set as `None (0)`
components in the Tasmota Template or Module. If the interface detects that a meter descriptor GPIO conflicts with a Tasmota GPIO setting, the interface will generate a "duplicate GPIO defined" error in the log and the meter descriptor will be ignored.
The Smart Meter Interface provides a means to connect many kinds of meters to Tasmota. **The following types of meter protocols are supported:**
- ascii OBIS telegrams emitted from many smart meters and also from P1 meter interface - ascii OBIS telegrams emitted from many smart meters and also from P1 meter interface
- binary SML OBIS telegram emitted from many smart meters - binary SML OBIS telegram emitted from many smart meters
- binary EBUS telegram emitted by many heaters and heat pumps (e.g. Vaillant, Wolf) - binary EBUS telegram emitted by many heaters and heat pumps (e.g., Vaillant, Wolf)
- binary MODBUS telegram used by many power meters - binary MODBUS telegram used by many power meters
- binary RAW telegram decodes all kinds of binary data eg EMS heater bus - binary RAW telegram decodes all kinds of binary data eg EMS heater bus
- counter interface (uses Tasmota counter storage) for e.g. reed contacts either in polling or IRQ mode - counter interface (uses Tasmota counter storage) for e.g., reed contacts either in polling or IRQ mode
There may be more than one software serial driven meter. There are dozens of variants and use cases for this driver and this requires a means of defining these variants. This is done through so called [meter descriptors](Smart-Meter-Interface-Descriptors). There are many different meters that use the same protocol. There are multitudes of variants and use cases. A meter can be defined by using compilation time `#define` pragmas. This requires recompiling the firmware to make modifications.
A method exists already in Tasmota to define a meter by `#define` pragmas in the compiler. This requires recompiling the driver after each modification. This interface provides a means of specifying these definitions through [meter descriptors](Smart-Meter-Interface-Descriptors). This method uses the [scripting language](Scripting-Language) editor to define the descriptors. In this way, only one firmware binary version is required and a modification can be made easily "on the fly".
The new, preferred, method uses the scripting language editor to define the descriptors in an `>M` section. For this only one firmware binary version is required and a modification can be made easily "on the fly". **Note:** If no `>M` section is found in the script or if the scripting language is not compiled, the driver reverts to the default `#define` definition(s).
The driver reverts to the default `#define` definition if no `>M` section is found in the script or [scripting](Scripting-Language) is not compiled.
## Descriptor Syntax ## Descriptor Syntax
Define a script `>M <n>` section with the number of connected meters. Up to five meters may be defined - e.g. `>M 3`
### Meter Declaration ### 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>}` `+<M>,<rxGPIO>,<type>,<flag>,<parameter>,<jsonPrefix>{,<txGPIO>,<txPeriod>,<cmdTelegram>}`
- `M` - meter number - `<M>` - meter number
- `rxGPIO` - meter data receive GPIO - `<rxGPIO>` - meter data receive GPIO
- `type` - meter type of meter - `<type>` - meter type of meter
- `o`=obis ASCII type of coding - `o`=obis ASCII type of coding
- `s`=sml binary smart message coding - `s`=sml binary smart message coding
- `c`=counter type - `c`=counter type
@ -36,30 +35,29 @@ Syntax
- `m`=modbus binary coding - `m`=modbus binary coding
- `p`=PZEM - `p`=PZEM
- `r`=raw binary coding (any binary telegram) - `r`=raw binary coding (any binary telegram)
- `flag` - counter flag - `<flag>` - counter flag
- 0=without pullup - 0=without pullup
- 1=with pullup - 1=with pullup
- `parameter` - parameters according to meter type - `<parameter>` - parameters according to meter type
- for `o,s,e,m,r`: serial baud rate - for `o,s,e,m,r`: serial baud rate
- for `c`: - for `c`:
- positive value = counter poll interval - positive value = counter poll interval
- negative value = debounce time (milliseconds) for irq driven counters - negative value = debounce time (milliseconds) for irq driven counters
- `jsonPrefix` - prefix for Web UI and MQTT JSON payload. Up to 7 characters - `<jsonPrefix>` - prefix for Web UI and MQTT JSON payload. Up to 7 characters
- `txGPIO` - meter command transmit GPIO - `<txGPIO>` - meter command transmit GPIO
- `txPeriod` - number of 250ms increments. Period to repeat the transmission of commands to the meter - `<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 - `<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
Examples: Examples:
`+1,3,o,0,9600,OBIS` `+1,3,o,0,9600,OBIS`
`+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010` `+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010`
### Meter Metrics ### 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. Each meter typically provides multiple metrics (voltage, power, humidity, etc.) which it measures. An entry for each metric to be collected `#define MAX_VARS N` (n = `1..16`) must be specified. An entry defines how to decode the data and put it into variables.
`1,1-0:1.8.0*255(@1,consumption,KWh,Total_in,4` `<M>,<decoder>@<scale>,<label>,<UoM>,<var>,<precision>`
- `<M>` - meter number to which this decoder belongs
- Meter number - `<decoder>` - decoding specification. Decode OBIS as ASCII; SML, EBUS, RAW as HEX ASCII
- 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 - 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 - 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 - EBUS,RAW: hex values of EBUS,RAW block to compare
@ -69,20 +67,22 @@ Each meter typically provides multiple metrics (voltage, power, humidity, etc.)
- `uuuu` = extract this unsigned word - `uuuu` = extract this unsigned word
- `ssss` = extract this signed word - `ssss` = extract this signed word
- `ffffffff` = extract this float value - `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. - 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 e.g., 1,xxxx5017xxuu@b0:1,Solarpumpe,,Solarpump,0
- 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 - 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 e.g., 1,010404ffffffffxxxx@i0:1,Voltage P1,V,Voltage_P1,2
- `@` decoding definition termination character - `@` decoding definition termination character
- scaling factor (divisor) - `<scale> - scaling factor (divisor)
This can be a fraction (e.g., 0.1 => result * 10), or a negative value 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 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) - `<label>` - web UI label (max 23 chars)
- Unit of measure (max 7 chars) - `<UoM>` - unit of measure (max 7 chars)
- MQTT variable name (max 23 chars) - `<var>` - MQTT variable name (max 23 chars)
- Number of decimals (decimal precision) - `<precision>` - number of decimal places
Add 16 to transmit the data immediately. Otherwise it is transmitted on [`TelePeriod`](Commands#teleperiod) Add 16 to transmit the data immediately. Otherwise it is transmitted on [`TelePeriod`](Commands#teleperiod)
e.g., `1,1-0:1.8.0*255(@1,consumption,KWh,Total_in,4`
`#` character terminates the list `#` character terminates the list
**Special Commands** **Special Commands**
@ -92,7 +92,7 @@ with the '=' char at the beginning of a line you may do some special decoding
- `=m` perform arithmetic (`+,-,*,/`) on the metric. Use `#` before a number to designate a constant value - `=m` perform arithmetic (`+,-,*,/`) on the metric. Use `#` before a number to designate a constant value
example: example:
`=m 3+4+5/#3` add result of decoder entry 3,4,5 and divided by 3 (i.e., average) `=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 - `=d` calculate difference between metric values decoded at time interval
example: example:
`=d 3 10` calculate 10 second interval difference of decoder entry 3 `=d 3 10` calculate 10 second interval difference of decoder entry 3
- `=h` html text (up to 30 chars) - `=h` html text (up to 30 chars)