Property Vectors

Instances of these classes are created automatically as data is received from the INDI server, typically you would read their attributes to display values on a client.

You should never need to instantiate these classes yourself.

All these vectors are mappings of membername to membervalue, and have the following methods and attributes:

Common Methods - All the vector classes have the following methods:

member(membername)

Returns the member object

memberlabel(membername)

Returns the member label, given a member name

members()

Returns a dictionary of member objects

async create_clientevent(eventtype=”ClientEvent”, **payload)

Creates a ClientEvent, and calls the IPyClient rxevent co-routine

This can be used to generate an event which may be of use to the programmer if the rxevent co-routine processes data in some way, and it is wanted to inject data into that process for any purpose.

The event will be a ClientEvent object, the attribute eventtype is by default “ClientEvent” but can be set to any string, the payload can be any kwargs wanted.

An example of using the create_clientevent method is at:

https://github.com/bernie-skipole/inditest/blob/main/docexamples/clientevent.py

snapshot()

Take a snapshot of the vector and returns an object which is a restricted copy of the current state of the vector. Vector methods for sending data will not be available. This copy will not be updated by events. This is provided so that you can handle the vector data, without fear of the value changing.

The snapshot will have the same common attributes and methods as the vector, apart from the snapshot and create_clientevent methods, and the device attribute. It will also have the extra methods:

dictdump(inc_blob=False)

Returns a dictionary of this vector, with datetime objects converted to strings. Set inc_blob to True to include BLOB values in the dictionary.

dump(fp, indent=None, separators=None, inc_blob=False)

Serialize the snapshot as a JSON formatted stream to fp, a file-like object. This uses the Python json module which always produces str objects, not bytes objects. Therefore, fp.write() must support str input. Set inc_blob to True to include BLOB values in the file.

dumps(indent=None, separators=None, inc_blob=False)

Returns a JSON string of the snapshot. Set inc_blob to True to include BLOB values in the string.

Common Attributes - All the vector classes have the following attributes:

self.name

self.label

self.group

self.state

One of “Idle”, “Ok”, “Busy” or “Alert”

self.message

When values are received from the server, the values may have an optional message set. This attribute holds the last message received.

self.message_timestamp

If a message is received, this holds the UTC datetime of the message.

self.devicename

self.user_string

This is initially an empty string, but can be set by your code to any string you like.

self.itemid

An integer associated with this vector when the client first learns of the vector. Created by calling the client.create_itemid() method.

self.timestamp

A UTC datetime object, updated from the server as values are received.

self.timeout

A float, suggested timeout for updating a value.

self.perm

One of “ro”, “wo” or “rw”. Not applicable to Light Vector, which is read only.

self.vectortype

Set to Vector type string such as ‘SwitchVector’, ‘NumberVector’ etc.

self.enable

If self.enable is False, this property has been ‘deleted’.

self.device

The device object owning this vector. This attribute is not available in the ‘snapshot’.

As data is received these vectors are created or updated and are available via ipyclient[devicename][vectorname]

class SwitchVector(event)

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.

As data is received, this vector is a mapping of membername:membervalue where membervalue is the ‘On’ or ‘Off’ string.

async send_newSwitchVector(timestamp=None, members={})

Transmits the vector (newSwitchVector) and the members given in the members dictionary which consists of member names:values to be sent. The values should be strings of either On or Off. This method will encode and transmit the xml, and change the vector state to busy. If no timestamp is given, a current UTC time will be created.

As well as the common attributes, the switch vector has a rule attribute.

self.rule

Applicable to Switch Vectors only, in which case it will be one of “OneOfMany”, “AtMostOne” or “AnyOfMany”.

For example, if the attribute is “OneOfMany”, of the members of this vector, one, and only one can be “On”.

class LightVector(event)

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

This class has no ‘send_newLightVector method, since lights are read-only

As data is received, this vector is a mapping of membername:membervalue where membervalue is the string of ‘Idle’, ‘Ok’, ‘Busy’ or ‘Alert’.

class TextVector(event)

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

As data is received, this vector is a mapping of membername:membervalue where membervalue is the string received.

async send_newTextVector(timestamp=None, members={})

Transmits the vector (newTextVector) with members and values. members is a dictionary of membernames:text string values. The spec requires text vectors to be sent with all members, so if the given members dictionary only includes changed values, the remaining members with unchanged values will still be sent. This method will transmit the vector and change the vector state to busy. If no timestamp is given, a current UTC time will be created.

class NumberVector(event)

A NumberVector is used to send and receive numbers between instrument and client. As data is received, this vector is a mapping of membername:membervalue where membervalue is the string of the number taken from the received xml. The INDI spec defines a number of formats, including degrees:minutes:seconds so this class includes methods to obtain the number as a float, and to create a string formatted as the particular member requires. The member objects contain further information label, format spec, minimum, maximum and step size. To obtain the member object, as opposed to the member value, use the members() method.

getfloatvalue(membername)

Given a membername of this vector, returns the number as a float

getformattedvalue(membername)

Given a membername of this vector, returns the number as a formatted string

async send_newNumberVector(timestamp=None, members={})

Transmits the vector (newNumberVector) with members and values. members is a dictionary of membernames:number values, the values can be integers, floats or strings, if not strings they will be converted to strings. The spec requires number vectors to be sent with all members, so if the given members dictionary only includes changed values, the remaining members with unchanged values will still be sent. This method will transmit the vector and change the vector state to busy. If no timestamp is given, a current UTC time will be created.

Note the ‘SnapNumberVector’ object returned by the snapshot method also has the getfloatvalue and get formattedvalue methods.

class BLOBVector(event)

A BLOBVector is used to send and receive Binary Large Objects between instrument and client. As data is received this vector will be a mapping of membername to membervalue where membervalue will be a binary string of the received BLOB. This binary string has been decoded from the received XML and from the b64 encoding used. The member object contains further information, label, blobsize and blobformat. To obtain the member object, as opposed to the member value, use the members() method.

async send_newBLOBVector(timestamp=None, members={})

Transmits the vector (newBLOBVector) with new BLOB members This method will transmit the vector and change the vector state to busy. The members dictionary should be {membername:(value, blobsize, blobformat)} The value could be a bytes object, a pathlib.Path, a string path to a file or a file-like object. If blobsize of zero is used, the size value sent 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. blobformat should be a file extension, such as ‘.png’. If it is an empty string and value is a filename, the extension will be taken from the filename.