diff --git a/docs/Smart-Meter-Interface.md b/docs/Smart-Meter-Interface.md index 25ad9d5c19..eb59e1e533 100644 --- a/docs/Smart-Meter-Interface.md +++ b/docs/Smart-Meter-Interface.md @@ -148,7 +148,7 @@ Each meter typically provides multiple metrics (energy, voltage, power, current | Parameter | Description | | :--- | :--- | | `` | The meter number to which this decoder belongs | -| `` | **Decoding specification**: OBIS as ASCII; SML, EBus, VBus, MODBus, RAW as HEX ASCII etc. _No space characters allowed in this section!_
**OBIS**: ASCII OBIS code terminated with `(` character which indicates the start of the meter value
**Counter**: ASCII code 1-0:1.8.0\*255 for counter value, code 1-0:1.7.0\*255 for pulse rate (e.g. for actual power value)
**SML**: SML binary OBIS as hex terminated with `0xFF` indicating start of SML encoded value
**EBus, MODBus, RAW** - hex values of data blocks to compare:
- `xx` = ignore value (1 byte) or `xN` = ignore N bytes
- `ss` = extract a signed byte
- `uu` = extract an unsigned byte
- `UUuu` = extract an unsigned word (high order byte first)
- `uuUU` = extract an unsigned word (low order byte first)
- `UUuuUUuu` = extract an unsigned long word (high order byte first)
- `uuUUuuUU` = extract an unsigned long word (low order byte first)
- `SSss` = extract a signed word (high order byte first)
- `ssSS` = extract a signed word (low order byte first)
- `SSssSSss` = extract a signed long word (high order byte first)
- `ssSSssSS` = extract a signed long word (low order byte first)
- **on long word values**, if a trailing s is added at the end of the mask, word order is reversed
- `bcdN` = extract a binary coded decimal N=2..12
- `ffffffff` = extract a float value - IEEE754 decode
- `FFffFFff` = extract a reverse float value - IEEE754 decode
- `kstr` = decode KAMSTRUP data
- `pm(x.y.z)` = pattern match(asci obis code)
- `pm(hHHHHHH)` = pattern match(hex obis code)
- `pm(rHHHHHH)` = pattern match(any hex pattern)

if using **VBus** - hex values of data blocks to compare:
- `AAffffaddrff0001ffff` = VBus-specific hex header: `AA`-sync byte, `addr`-the reversed address of the device. To find his out first look up the known [hex address of the device](http://danielwippermann.github.io/resol-vbus/vbus-packets.html). E.g. Resol DeltaSol BS Plus is `0x4221`. Reverse it (without `0x`) and you will get `21 42` hex characters. Now turn on raw dump mode using command `sensor53 d1` and look for rows starting with `aa`, containing your reversed address at position 4 and 5 and `00 01` hex characters at position 7 and 8. If found, the entire header will be 10 hex characters long including `aa` (20 ascii chars without space, e.g. for Resol DeltaSol BS Plus this will be `AA100021421000010774`). At position 9 you see the number of frames containing readable data. To turn off raw dump use `sensor53 d0`.
- `v` = VBus protocol indicator
- `oN` = extract data from offset `N` (see offsets of your device in [VBus protocol documentation](http://danielwippermann.github.io/resol-vbus/vbus-packets.html))
- `u` or `s` = extract unsigned or signed data
- `w` or `b` = extract word or byte
**End of decoding**: `@` indicates termination of the decoding procedure.
- `(` following the `@` character in case of obis decoder indicates to fetch the 2. value in brackets, not the 1. value. (e.g. to get the second value from an obis like `0-1:24.2.3(210117125004W)(01524.450*m3)`)
- decoding multiple values coming in brackets after each other is possible with `(@(0:1`, `(@(1:1`, `(@(2:1` and so on (e.g. to get values from an obis like `0-0:98.1.0(210201000000W)(000000.000*kWh)(000000.000*kWh)`)
- 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,Solarpump,,Solarpump,0`)
- in case of MODBus/Kamstrup, `ix:` designates the index (x = `0..n`) referring to the requested block in the transmit section of the meter definition +| `` | **Decoding specification**: OBIS as ASCII; SML, EBus, VBus, MODBus, RAW as HEX ASCII etc. _No space characters allowed in this section!_
**OBIS**: ASCII OBIS code terminated with `(` character which indicates the start of the meter value
**Counter**: ASCII code 1-0:1.8.0\*255 for counter value, code 1-0:1.7.0\*255 for pulse rate (e.g. for actual power value)
**SML**: SML binary OBIS as hex terminated with `0xFF` indicating start of SML encoded value
**EBus, MODBus, RAW** - hex values of data blocks to compare:
- `xx` = ignore value (1 byte) or `xN` = ignore N bytes
- `ss` = extract a signed byte
- `uu` = extract an unsigned byte
- `UUuu` = extract an unsigned word (high order byte first)
- `uuUU` = extract an unsigned word (low order byte first)
- `UUuuUUuu` or `U32` = extract an unsigned long word (high order byte first)
- `uuUUuuUU` or `u32` = extract an unsigned long word (low order byte first)
- `SSss` = extract a signed word (high order byte first)
- `ssSS` = extract a signed word (low order byte first)
- `SSssSSss` or `S32` = extract a signed long word (high order byte first)
- `ssSSssSS` or `s32` = extract a signed long word (low order byte first)
- **on long word values**, if a trailing s is added at the end of the mask, word order is reversed
- `U64` = extract an unsigned 64 long word
- `u64` = extract an unsigned 64 long word (low order byte first)
- `bcdN` = extract a binary coded decimal N=2..12
- `ffffffff` = extract a float value - IEEE754 decode
- `FFffFFff` = extract a reverse float value - IEEE754 decode
- `kstr` = decode KAMSTRUP data
- `pm(x.y.z)` = pattern match(asci obis code)
- `pm(hHHHHHH)` = pattern match(hex obis code)
- `pm(rHHHHHH)` = pattern match(any hex pattern)

if using **VBus** - hex values of data blocks to compare:
- `AAffffaddrff0001ffff` = VBus-specific hex header: `AA`-sync byte, `addr`-the reversed address of the device. To find his out first look up the known [hex address of the device](http://danielwippermann.github.io/resol-vbus/vbus-packets.html). E.g. Resol DeltaSol BS Plus is `0x4221`. Reverse it (without `0x`) and you will get `21 42` hex characters. Now turn on raw dump mode using command `sensor53 d1` and look for rows starting with `aa`, containing your reversed address at position 4 and 5 and `00 01` hex characters at position 7 and 8. If found, the entire header will be 10 hex characters long including `aa` (20 ascii chars without space, e.g. for Resol DeltaSol BS Plus this will be `AA100021421000010774`). At position 9 you see the number of frames containing readable data. To turn off raw dump use `sensor53 d0`.
- `v` = VBus protocol indicator
- `oN` = extract data from offset `N` (see offsets of your device in [VBus protocol documentation](http://danielwippermann.github.io/resol-vbus/vbus-packets.html))
- `u` or `s` = extract unsigned or signed data
- `w` or `b` = extract word or byte
**End of decoding**: `@` indicates termination of the decoding procedure.
- `(` following the `@` character in case of obis decoder indicates to fetch the 2. value in brackets, not the 1. value. (e.g. to get the second value from an obis like `0-1:24.2.3(210117125004W)(01524.450*m3)`)
- decoding multiple values coming in brackets after each other is possible with `(@(0:1`, `(@(1:1`, `(@(2:1` and so on (e.g. to get values from an obis like `0-0:98.1.0(210201000000W)(000000.000*kWh)(000000.000*kWh)`)
- 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,Solarpump,,Solarpump,0`)
- in case of MODBus/Kamstrup, `ix:` designates the index (x = `0..n`) referring to the requested block in the transmit section of the meter definition | `` | scaling factor (divisor) or string definition
This can be a fraction (e.g., `0.1` = result * 10), or a negative value. When decoding a string result (e.g. meter serial number), use `#` character for this parameter _(Note: only one string can be decoded per meter!)_. For OBIS, you need a `)` termination character after the `#` character. | | `` | optional offset must precede with + or - sign, note: offset is applied before scale!| | `