-
Notifications
You must be signed in to change notification settings - Fork 19
010 Command Syntax
see 300-Source-of-poll-list-and-poll-interval for where the poll_items list is taken from!
poll_items is a list of tuples where you could add your poll items to.
These items get polled cyclicly (frequency: poll_interval) and get published to MQTT broker and/or written to Viessdata csv.
([poll_cycle,] <name>, <address>, <length> [, <scale/type> [, <signed>]])
type: string
is the name of the datapoint which will get published to MQTT as {dpname}. Better avoid blanks etc.
A slash ('/') creates a new topic tree level, might get used for grouping.
type: int
is the address used to read the datapoint data/value. Can get entered as hex (leading '0x') or decimal.
type: int
is the number of bytes to get read
parameter is optional. If ommitted value will get returned as hex byte string without leading '0x'.
type: This parameter can be a number (int, float) or a string.
-
In case of a number the read data will get mutiplied by the given scale value and returned as decimal number. So use 1 to show decimal instead of hex.
-
In case of a string, the following options are implemented:
-
'raw': value gets returned as hex byte string without leading '0x' -
'vdatetime': 'stupid' Viessmann date/time (w. Vitodens) -
'vcaldatetime': 'stupid' Viessmann date/time (w. Vitocal) -
'unixtime': bytes interpreted as Unix timestamp -
'schedvdens'for 2-byte schedules (start, stop) -
'schedvcal'for 3-byte schedules (start, stop, mode) -
'utf8': bytes interpreted as utf8 string -
'utf16': bytes interpreted as utf16 string -
'bool'retunrs True if val != 0 else False -
'boolinv'returns True if val == 0 else False -
'onoff'retunrs ON if val != 0 else OFF -
'offon'returns ON if val == 0 else OFF -
'bin'returns data binary according to data/byte length -
'f:<frmt>'allows to specify any format accepted in a f" clause -
'b:<startbyte>[:<lastbyte>[:<mask>[:<endian>]]]'ByteBit Filter: see here
-
If ByteBit Filter is used, the item tuple may expand to
([poll_cycle,] <name>, <address>, <length>, <ByteBitFilter> [, <scale/type> [, <signed>]])
type: bool
defines if numerical data will get converted signed (FF=-1) or unsigned (FF=255). True and true interpreted as True, anything else interpreted as False (default if ommited)
type: int | str
Since version 1.2.0 there is an optional entry to allow the item getting polled only every x-th poll cycle.
With version 1.11.0 the poll_groups dict got introduced, allowing to change the poll_cycle at run-time using the setpollcycle action command. In this case use the key (str) of an according poll_group to set the poll_cycle for the poll item/s.
In case poll_cycle is 0, the item gets polled only once on the first cycle and on command forcepoll. poll_cycle < 0 disables the item.
You may use groups to group items to certain poll intervalls. Add as many definitions as you like.
You may use action commands setpollcycle and setpollinterval during runtime to alter the values.
# === define your groups here. you may extend or alter the dict!
poll_groups = {
"ONCEONLY" : 0, # polled only once on start-up and on reception of forcepoll command
"ALWAYS" : 1, # on each polling, same as ommitted
"OFTEN" : 5,
"SOMETIMES" : 60,
"RARELY" : 1000,
"DEBUG" : -1, # < 0 for never
}
poll_interval = 30
poll_items = [
("ONCEONLY", "device_ident", 0xf8, 8),
("ONCEONLY", "WPR3_Raumsolltemp_HK1", 0x01DB, 2, 0.1), # this is a /set item !-)
("RARELY", "scop_hk2", 0x1681, 1, 0.1, False),
("RARELY", "scop_ww", 0x1682, 1, 0.1, False),
("SOMETIMES", "outside_temperature", 0x0101, 2, 0.1, True),
("SOMETIMES", "sk_pumpe_rpm", 0xB421, 2, 1, False),
(30, "expansionsventil_position", 0xB424, 2, 1, False), # this is not in a (pre-defined) group
("compressor_power", 0xB423, 2, 1, False), # this gets polled each cycle
...
]
# scaling values
("AussenTemp", 0x0800, 2, 0.1, True),
("Betriebsstunden", 0x08A7, 4, 2.7777778e-4, False), # 1/3600
# use of ByteBit Filter; read once - derive all
("Frostgefahr", 0x2500, 22, 'b:16', 'bool'),
("RTS_akt", 0x2500, 22, 'b:12:13', 0.1, False),
# hex or decimal writing
("DeviceIdent", 0xf8, 8),
("DeviceIdent", 248, 8),
# use of poll_cycle feature
(50, "cop", 0x1680, 1, 0.1),
(0, "Herstellnummer_Kessel", 0xf010, 16, 'utf8'),
# sub-topic example
("WP_HK1/Zirkulation", 0x0490, 1, 'onoff'),
("WP_HK1/Vorlauftemp", 0x16B2, 2, 0.1, False),
("WP_HK1/Ruecklauftemp", 0x16B3, 2, 0.1, False),
("WP_HK1/Vorlaufsolltemperatur", 0x1800, 2, 0.1, False),
These commands can get used to request reading or writing of values from/to your Optolink device.
The whole command always is a string. Command items/parts are sperated by ;.
Since it is already a string, ommit further ' or " (even those will be erased on reception). Also blanks or line breaks get erased on reception.
<command>; <address>; <length> [; <scale/type> [; signed]]
may be read or short r
same as for polling items, see here
If ByteBit Filter is used, the term may expand to
<command>; <address>; <length>; <ByteBitFilter> [; <scale/type> [; <signed>]]
<command>; <address>; <length>; <value>
may be write or short w
same as for polling items, see here
currently only integers (possible as hex with leading 0x also) as to be written as byte value are supported. So in case of scaled values perform the 'reverse scaling' by yourself. E.g. a setpoint 7.3 scaled by 1/10 has to be written as 73.
negative (decimal integer) values are possible since V1.4.2.2. With older versions you need to calculate the 2's complement of you value and write that. E.g. you want to write -150 to a 2-byte datapoint, calc 2^16 -150 = 65386 = 0xff6a
<command>; <address>; <value>
This is used to write 'complex' data points.
may be writeraw or short wraw
same as for polling items, see here
a hex byte string without leading '0x'
<command>; <fctcode>; <addr>; <length> [; data [; protid]]
This is used to perform (even) special requests such as Remote_Procedure_Call, PROZESS_READ/WRITE, ... . Also the Protocol/Message Identifier might get altered. For details see VS2 Message Format.
The Function Request is implemented only with VS2 protocol. With VS1 raw is easy to use.
may be request or short req
type: int
the function code to be performed. see VS2 Message Format
type: int
is the address used with the function request. Can get entered as hex (leading '0x') or decimal.
type: int
is the data lenght related to the function request. may be the lenght of the requested or transmitted data.
a hex byte string without leading '0x'. may be empty.
type: int, default: 0x00
Protocol|Message Identifier, see VS2 Message Format
<return_code>; <address>; <value>
- 01=success
- 03=ErrMsg, 15=NACK, 20=UnknB0_Err, 41=STX_Err, FD=PlLen_Err, FE=CRC_Err, FF=TimeOut, AA=HandleLost (all hex)
value in case of return_code 03 - ErrMsg (as known):
- 0x01: invalid address
- 0x04: invalid length
- 0x21: value out of bounds
writing a read only value may be ignored, might not return an error.
the datapoint address of the request. the format accords to settings.resp_addr_format.
the requested (rsp. written) value, or the payload data or full telegram in case of an error
-
read ambient temperature, scaled with sign:
- cmnd = read;0x0800;2;0.1;true
- resp = 1;2048;8.2
-
read DeviceIdent as raw:
- cmnd = read;0xf8;8
- resp = 1;248;20CB1FC900000114
-
write hotwater temperature setpoint:
- cmnd = write;0x6300;1;45
- resp = 1;25344;45
-
write level of heating curve to -15°C (Vitocal):
- cmnd = write;0x2006;2;0xff6a
- resp = 1;8198;65386
-
write heating period monday 08:30-13:00
- cmnd = writeraw;0x2000;4368FFFFFFFFFFFF
- resp = 1;8192;4368FFFFFFFFFFFF
'b:<startbyte>[:<lastbyte>[:<mask>[:<endian>]]]'
a sub-array of the data bytes starting at startbyte to lastbyte gets picked. If no lastbyte is given, only startbyte gets picked.
if mask is given (else missing or empty string) the mask gets applied (bit-wise AND junction) to the picked sub-array of bytes. mask can be decimal or hex (leading '0x') integer.
Attention: mask gets applied byte by byte 'left to right'. So if you have two bytes
00000110 00000000 which would be 6 as little endian, and you want to mask 4, you need the mask
00000100 00000000 which is 4<<8 = 0x0400 = 1024 as mask.
If the result gets evaluated as little endian, it gives 4.
endian might be 'little' or 'big'. If missing, little is default. Relevant only in case of using a scale (at least 1) to convert the hex data to decimal.
Remark: With version lower 1.4.0.0 the ByteBit Filter returns a decimal value by default (different to using read without ByteBit Filter). With those versions endian has to be set 'raw' to receive hex data.
additional explaination and examples see here
-
read Heissgas temperature of a Vitocal, scaled:
- cmnd = read;0xB40a;3;'b:0:1';0.1
- resp = 1;0xB40A;66.4
-
read room target temperature of a Vitodens, scaled without sign:
- cmnd = read;0x2500;22;'b:12:13';0.1;False
- resp = 1;0x2500;18.0
-
read Frostgefahr of a Vitodens as hex value:
- cmnd = read;0x2500;22;'b:16:16'
- resp = 1;0x2500;00
Instead of sending read/write requests as described above, you may send Optolink telegrams as hex strings to get forwarded to the device and the response to get received and passed back. This way you are completely free in communicating.
There are 2 froms of the raw communication:
In this mode the pure telegram string is sent to the Splitter, e.g. 4105000100f80402. The reception is based on timing only. As soon as no more data is received for settings_ini.fullraw_eot_time, the telegram is decided as being complete and the data get passed back.
If no data received within settings_ini.fullraw_timeout, the request returns without data.
In this mode the raw command is prefixed, separated by semicolon, e.g. raw;4105000100f80402. In this case the reception is based on the expected telegram format. The response telegram is checked formally based on the protocol specs. Length is taken from telegramm (if applicable), correctness or formal errors are detected and retured as return code, e.g. 1;064109010100f80420cb1fc9da.
This way with VS2/300 protocol the raw mode is slightly faster since it is not required to wait for 'eot_timeout' to determine the end of the telegram. With VS1/KW protocol there is no difference since KW spec does not include lenght info. Accordingly with VS1 the only return codes are 01 for success or FF if no reception at all within fullraw_timeout.