diff --git a/Smart-Meter-Interface.md b/Smart-Meter-Interface.md index b62bd305..dcc2c695 100644 --- a/Smart-Meter-Interface.md +++ b/Smart-Meter-Interface.md @@ -2,33 +2,32 @@ [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 - 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 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". - -The driver reverts to the default `#define` definition if no `>M` section is found in the script or [scripting](Scripting-Language) is not compiled. +**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). ## Descriptor Syntax +Define a script `>M ` section with the number of connected meters. Up to five meters may be defined - e.g. `>M 3` ### Meter Declaration -Define an `>M` section with the number of meters to be connected (up to 5) - e.g. `>M 3` - -Syntax `+,,,,,{,,,}` -- `M` - meter number -- `rxGPIO` - meter data receive GPIO -- `type` - meter type of meter +- `` - meter number +- `` - meter data receive GPIO +- `` - meter type of meter - `o`=obis ASCII type of coding - `s`=sml binary smart message coding - `c`=counter type @@ -36,30 +35,29 @@ Syntax - `m`=modbus binary coding - `p`=PZEM - `r`=raw binary coding (any binary telegram) -- `flag` - counter flag +- `` - counter flag - 0=without pullup - 1=with pullup -- `parameter` - parameters according to meter type +- `` - 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 + - negative value = debounce time (milliseconds) for irq driven counters +- `` - prefix for Web UI and MQTT JSON payload. Up to 7 characters +- `` - meter command transmit GPIO +- `` - number of 250ms increments. Period to repeat the transmission of commands to the meter +- `` - 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: `+1,3,o,0,9600,OBIS` `+1,3,m,0,9600,MODBUS,1,1,01040000,01040002,01040004,01040006,01040008,0104000a,0104000c,0104000e,01040010` ### 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` - -- Meter number -- Data decoding specification. Decode OBIS as ASCII; SML, EBUS, RAW as HEX ASCII +`,@,