Properties

A property vector is an object containing one or more ‘members’. For example a NumberVector will contain one or more NumberMember objects, each containing a number value.

This section documents the property vectors created and set into the device, and also the associated members.

All these vectors have arguments name, label, group, perm, state except for LightVector which does not have permission (being a read only value).

name is the vector name, any unique name consistent with xml can be used (normal ascii characters), however if you are working with astronomical instruments, and want compatability with other drivers and clients, see the site:

https://indilib.org/develop/developer-manual/101-standard-properties.html

Which provides a convention for property and member names.

label is a string which can be used by the client, if not given it will be set equal to the name.

group is a further label used by the client, which can be used to group properties together. It can be left blank if not used.

perm is the permission - set to one of ‘ro’, ‘wo’, ‘rw’ - so ‘ro’ means the client can only read the vector values, not set them.

state can be set to one of ‘Idle’, ‘Ok’, ‘Busy’ or ‘Alert’. Typically the client displays this in an appropriate colour.

The state can be changed when calling a send_defVector, or send_setVector method where it is an optional argument of these methods. If the send method has argument state=None (the default), then the state attribute remains unchanged, however if the argument is set to one of the state values, then the state attribute is changed, and the client will receive the new state.

Further attributes

The timeout attribute is not set in the arguments, but is always initially set to ‘0’.

timeout indicates to the client the worst-case time it might take to change the value to something else.

The default of ‘0’ implies that the vector will be updated in a minimal time should the client request it.

This attribute is a string numeric value which can be changed when calling a send_defVector, or send_setVector method where it is an optional argument of these methods. If the send method has argument timeout=None (the default), then the timeout attribute remains unchanged, however if the argument is set to a numeric string, then the timeout attribute is changed, and the client will receive the new timeout.

From the indi specification

“Each Property has a timeout value that specifies the worst-case time it might take to change the value to something else. The Device may report changes to the timeout value depending on current device status. Timeout values give Clients a simple ability to detect dysfunctional Devices or broken communication and also gives them a way to predict the duration of an action for scheduling purposes…”

enable is by default True, and is automatically set to False if the send_delProperty() method is called. When False no further data is sent by this property and any incoming values are ignored, until the enable attribute is set True again. Calling send_delProperty() therefore has the effect of removing the property from the client.

If in the initial state of the device, it is required that a particular property should be hidden, then when the vector is first created, set vector.enable = False, and the vector will be disabled until the enable attribute is set True, and the vector send_defVector() method called, which informs the client of the existence of this property.

Each vector is also a mapping of membername to memberVALUE - note, not member object, rather it is the value held by the member. In the LEDDriver example, the value of the vector member is set by:

event.vector["ledswitchmember"] = newvalue

Numeric values are set into vectors as strings, this is to explicitly control how numbers are formatted and sent in the protocol, the only exception is blobsize, where the number should be an integer.

Each member has a name and label, the label is a string which can be used by the client, if not given it will be set equal to the name.

When transmitting a vector, using the send_setVector or send_setVectorMembers methods, the method has a timestamp argument. The specification requires this to be a UTC value. You can either create a datetime.datetime object with timezone UTC, or leave the argument as None, in which case the method will automatically insert a UTC timestamp.

One possible way you may want to create your own timestamp is:

from datetime import datetime, timezone

timestamp = datetime.now(tz=timezone.utc)

Text

A TextVector takes one or more TextMember objects.

class TextMember(name, label=None, membervalue='')

Contains a text string

class TextVector(name, label, group, perm, state, textmembers)

A TextVector is used to send and receive text between instrument and client.

async send_defVector(message='', timestamp=None, timeout=None, state=None)

Transmits the vector definition to the client.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

async send_delProperty(message='', timestamp=None)

Informs the client this vector is not available, it also sets an ‘enable’ attribute to False, which stops any data being transmitted between the client and this property vector.

Setting vector.enable to True re-enables communications.

The message argument is any appropriate string which the client could display to the user.

The timestamp should be either None or a datetime.datetime object. If the timestamp is None a UTC value will be inserted.

async send_setVector(message='', timestamp=None, timeout=None, state=None, allvalues=True)

Transmits the vector (setTextVector) and members with their values to the client. Typically any changed member value should be set prior to transmission.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

If allvalues is True, all values are sent.

If allvalues is False, only values that have changed will be sent, saving bandwidth. If no values have changed, the vector will not be sent, if you need to ensure the vector message, state or time values are sent to the client, then use the more explicit send_setVectorMembers method instead.

async send_setVectorMembers(message='', timestamp=None, timeout=None, state=None, members=[])

Transmits the vector (setTextVector) and members with their values to the client. Similar to the send_setVector method however the members list specifies the member names which will have their values sent.

This allows members to be explicitly specified. If the members list is empty then a vector will still be sent, empty of members, which may be required if just a state or message is to be sent.

Lights

A LightVector takes one or more LightMember objects.

class LightMember(name, label=None, membervalue='Idle')

A LightMember can only have one of ‘Idle’, ‘Ok’, ‘Busy’ or ‘Alert’ values

class LightVector(name, label, group, state, lightmembers)

A LightVector is an instrument indicator, and sends one or more members with values ‘Idle’, ‘Ok’, ‘Busy’ or ‘Alert’. In general a client will indicate this state with different colours.

async send_defVector(message='', timestamp=None, timeout=None, state=None)

Transmits the vector definition to the client.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

async send_delProperty(message='', timestamp=None)

Informs the client this vector is not available, it also sets an ‘enable’ attribute to False, which stops any data being transmitted between the client and this property vector.

Setting vector.enable to True re-enables communications.

The message argument is any appropriate string which the client could display to the user.

The timestamp should be either None or a datetime.datetime object. If the timestamp is None a UTC value will be inserted.

async send_setVector(message='', timestamp=None, timeout=None, state=None, allvalues=True)

Transmits the vector (setLightVector) and members with their values to the client. Typically any changed member value should be set prior to transmission.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

For Light Vectors the timeout value is not used, but is included in the arguments to match other send_vectors.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

If allvalues is True, all values are sent.

If allvalues is False, only values that have changed will be sent, saving bandwidth. If no values have changed, the vector will not be sent, if you need to ensure the vector message, state or time values are sent to the client, then use the more explicit send_setVectorMembers method instead.

async send_setVectorMembers(message='', timestamp=None, timeout=None, state=None, members=[])

Transmits the vector (setLightVector) and members with their values to the client. Similar to the send_setVector method however the members list specifies the member names which will have their values sent.

This allows members to be explicitly specified. If the members list is empty then a vector will still be sent, empty of members, which may be required if just a state or message is to be sent.

Switches

A SwitchVector takes one or more SwitchMember objects.

class SwitchMember(name, label=None, membervalue='Off')

A SwitchMember can only have one of ‘On’ or ‘Off’ values

class SwitchVector(name, label, group, perm, rule, state, switchmembers)

A SwitchVector sends and receives one or more members with values ‘On’ or ‘Off’. It also has the extra attribute ‘rule’ which can be one of ‘OneOfMany’, ‘AtMostOne’, ‘AnyOfMany’. These are hints to the client how to display the switches in the vector.

OneOfMany - of the SwitchMembers in this vector, one (and only one) must be On.

AtMostOne - of the SwitchMembers in this vector, one or none can be On.

AnyOfMany - multiple switch members can be On.

async send_defVector(message='', timestamp=None, timeout=None, state=None)

Transmits the vector definition to the client.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

async send_delProperty(message='', timestamp=None)

Informs the client this vector is not available, it also sets an ‘enable’ attribute to False, which stops any data being transmitted between the client and this property vector.

Setting vector.enable to True re-enables communications.

The message argument is any appropriate string which the client could display to the user.

The timestamp should be either None or a datetime.datetime object. If the timestamp is None a UTC value will be inserted.

async send_setVector(message='', timestamp=None, timeout=None, state=None, allvalues=True)

Transmits the vector (setSwitchVector) and members with their values to the client. Typically any changed member value should be set prior to transmission.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

If allvalues is True, all values are sent.

If allvalues is False, only values that have changed will be sent, saving bandwidth. If no values have changed, the vector will not be sent, if you need to ensure the vector message, state or time values are sent to the client, then use the more explicit send_setVectorMembers method instead.

async send_setVectorMembers(message='', timestamp=None, timeout=None, state=None, members=[])

Transmits the vector (setSwitchVector) and members with their values to the client. Similar to the send_setVector method however the members list specifies the member names which will have their values sent.

This allows members to be explicitly specified. If the members list is empty then a vector will still be sent, empty of members, which may be required if just a state or message is to be sent.

Numbers

A NumberVector takes one or more NumberMember objects.

class NumberMember(name, label=None, format='', min='0', max='0', step='0', membervalue='0')

Contains a number, the attributes inform the client how the number should be displayed.

format is a C printf style format, for example %7.2f means the client should display the number string with seven characters (including the decimal point as a character and leading spaces should be inserted if necessary), and with two decimal digits after the decimal point.

min is the minimum value

max is the maximum, if min is equal to max, the client should ignore these.

step is incremental step values, set to string of zero if not used.

The above numbers, and the member value must be set as a string, this explicitly controls how numbers are placed in the xml protocol.

class NumberVector(name, label, group, perm, state, numbermembers)

async send_defVector(message='', timestamp=None, timeout=None, state=None)

Transmits the vector definition to the client.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

async send_delProperty(message='', timestamp=None)

Informs the client this vector is not available, it also sets an ‘enable’ attribute to False, which stops any data being transmitted between the client and this property vector.

Setting vector.enable to True re-enables communications.

The message argument is any appropriate string which the client could display to the user.

The timestamp should be either None or a datetime.datetime object. If the timestamp is None a UTC value will be inserted.

async send_setVector(message='', timestamp=None, timeout=None, state=None, allvalues=True)

Transmits the vector (setNumberVector) and members with their values to the client. Typically any changed member value should be set prior to transmission.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

If allvalues is True, all values are sent.

If allvalues is False, only values that have changed will be sent, saving bandwidth. If no values have changed, the vector will not be sent, if you need to ensure the vector message, state or time values are sent to the client, then use the more explicit send_setVectorMembers method instead.

async send_setVectorMembers(message='', timestamp=None, timeout=None, state=None, members=[])

Transmits the vector (setNumberVector) and members with their values to the client. Similar to the send_setVector method however the members list specifies the member names which will have their values sent.

This allows members to be explicitly specified. If the members list is empty then a vector will still be sent, empty of members, which may be required if just a state or message is to be sent.

The number format also accepts an INDI style “m” to specify sexagesimal in the form “%<w>.<f>m”.

From the INDI spec:

<w> is the total field width
<f> is the width of the fraction. valid values are:
         9 -> :mm:ss.ss
         8 -> :mm:ss.s
         6 -> :mm:ss
         5 -> :mm.m
         3 -> :mm

         For example:

         to produce "-123:45" use %7.3m

         to produce "  0:01:02" use %9.6m

BLOBs

A BLOBVector takes one or more BLOBMember objects.

class BLOBMember(name, label=None, blobsize=0, blobformat='', membervalue=None)

Contains a ‘binary large object’ such as an image. The membervalue should be either None, a bytes object, a file-like object, or a path to a file.

Typically membervalue is left at None when creating a member, and only set to a value via vector[membername] = membervalue prior to calling the vector send_setVectorMembers method.

blobsize is the size of the BLOB before any compression, if left at zero, the length of the BLOB will be used. The member blobsize can be set by calling the vector.set_blobsize(membername, blobsize) method.

The BLOB format should be a string describing the BLOB, such as .jpeg

class BLOBVector(name, label, group, perm, state, blobmembers)

async send_defVector(message='', timestamp=None, timeout=None, state=None)

Transmits the vector definition to the client.

message is any suitable string for the client.

timestamp should be a datetime.datetime object or None, in which case a UTC value will be inserted.

If the timeout value is a string of a numeric value it will set this vectors timeout attribute. If it is None, the timeout attribute will remain unchanged.

This timeout indicates to the client how long it takes to effect a change of this vector.

The state should be either None - in which case no change to the state attribute will be made, or one of Idle, Ok, Busy or Alert.

async send_delProperty(message='', timestamp=None)

Informs the client this vector is not available, it also sets an ‘enable’ attribute to False, which stops any data being transmitted between the client and this property vector.

Setting vector.enable to True re-enables communications.

The message argument is any appropriate string which the client could display to the user.

The timestamp should be either None or a datetime.datetime object. If the timestamp is None a UTC value will be inserted.

async send_setVectorMembers(message='', timestamp=None, timeout=None, state=None, members=[])

Transmits the vector (setBLOBVector) and members with their values to the client. The members list specifies the member names which will have their values sent.

The member values can be set via vector[membername] = membervalue prior to calling this send_setVectorMembers method

Members contain either a bytes string, a file-like object, or a path to a file. If a file-like object is given, its contents will be read and its close() method will be called, so you do not have to close it.

set_blobsize(membername, blobsize)

Sets the size attribute in the blob member. If the default of zero is used, the size will be set to the number of bytes in the BLOB. The INDI standard specifies the size should be that of the BLOB before any compression, therefore if you are sending a compressed file, you should set the blobsize prior to compression with this method.

Note that BLOBVectors do not have a send_setVector method, it is considered the more explicit send_setVectorMembers should always be used for BLOB’s.