010 Command Syntax

Command Syntax for polling items in settings_ini

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.

Entry (tuple):

(<name>, <address>, <length> [, <scale/type> [, <signed>]])

name

type: string

is the name of the datapoint which will get published to MQTT as {dpname}.

address

type: int

is the address used to read the datapoint data/value. Can get entered as hex (leading '0x') or decimal.

length

type: int

is the number of bytes to get read

scale/type

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.

• In case of a string, the following options are implemented:

  • 'raw': value will get returned as hex byte string without leading '0x'.

  • 'vdatetime': 'stupid' Viessmann date/time (w. Vitodens)

  • 'unixtime': bytes interpreted as Unix timestamp

  • 'utf8': bytes interpreted as utf8 string

  • 'b:<startbyte>[:<lastbyte>[:<mask>:[<endian>]]]': ByteBit Filter: see here

If ByteBit Filter is used, the item tuple may expand to

(<name>, <address>, <length>, <ByteBitFilter> [, <scale/type> [, <signed>]])

signed

type: bool

defines if numerical data will get converted signed or unsigned. True and true interpreted as True, anything else interpreted as False (default if ommited)

poll_cycle

type: int

up from version 1.2.0.0 there is an optional entry to allow the item only getting polled ever x-th poll cycle:

([poll_cycle,] <name>, <address>, <length> [, <scale/type> [, <signed>]])

Examples

("AussenTemp", 0x0800, 2, 0.1, True),
("Betriebsstunden", 0x08A7, 4, 2.7777778e-4, False),  # 1/3600

("Frostgefahr, aktuelle RTS etc", 0x2500, 22, 'b:0:21::raw'),
("Frostgefahr", 0x2500, 22, 'b:16:16::raw'),
("RTS_akt", 0x2500, 22, 'b:12:13', 0.1, False),

("DeviceIdent", 0xf8, 8),
("DeviceIdent", 248, 8),

(50, "cop", 0x1680, 1, 0.1),

Command Syntax for Requests via MQTT and TCP/IP

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 empty spaces or line breaks get erased on reception.

Read Requests

<command>; <address>; <length> [; <scale/type> [; signed]]

command

may be read or short r

address, length, scale, signed

same as for polling items, see here

Write Requests (Value)

<command>; <address>; <length>; <value>

command

may be write or short w

address, length

same as for polling items, see here

value

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.

Write Raw Requests (hex byte string)

<command>; <address>; <value>

This is used to write 'complex' data points.

command

may be writeraw or short wraw

address

same as for polling items, see here

value

a hex byte string without leading '0x'

Response to Requests

<return_code>; <address>; <value>

return_code

• 01=success
• 03=ErrMsg, 15=NACK, 20=UnknB0_Err, 41=STX_Err, AA=HandleLost, FD=PlLen_Err, FE=CRC_Err, FF=TimeOut (all hex)

data in case of 03 - ErrMsg (as known):

• 0x01: invalid address
• 0x04: invalid length
• 0x21: value out of bounds

writing a read only value is ignored, does not return an error.

address

the datapoint address of the request

value

the requested (rsp. written) value, or the payload data or full telegram in case of an error

Examples

• 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 heating period monday 08:30-13:00

  • cmnd = writeraw;0x2000;4368FFFFFFFFFFFF
  • resp = 1;8192;4368FFFFFFFFFFFF

ByteBit Filter

'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. mask can be decimal or hex (leading '0x') integer.

endian might be 'little', 'big', 'raw'. If missing, little is default for non-masked values, raw is default if mask is given. 'raw' causes data being returned as hex byte string without leading '0x'.

additional explaination see here

Examples

• 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, scaled without sign:

  • cmnd = read;0x2500;22;'b:16:16::raw'
  • resp = 1;0x2500;00