Tools

This is a set of Python functions which read, and publish to your redis server. You may find them useful when creating a client gui, if your gui is Python based.

Functions are provided which open a redis connection, and return lists of devices, properties, elements etc., further functions create xml elements and publish them which transmits the values on to indiserver and hence the attached instruments.

These functions take the namedtuple redisserver as an argument and apply the key prefix as defined in the tuple to the redis keys.

Typically another process will be storing INDI data into redis. These functions can then be imported into your own GUI clent as a convenient way of accessing that data.

Your script could start with:

from indi_mr import redis_server, tools

redisserver = redis_server(host='localhost', port=6379)
rconn = tools.open_redis(redisserver)

and then using rconn and redisserver you could call upon the functions provided here.

Where a timestamp is specified, unless otherwise stated, it will be a string according to the INDI v1.7 white paper which describes it as:

A timeValue shall be specified in UTC in the form YYYY-MM-DDTHH:MM:SS.S. The final decimal and subsequent
fractional seconds are optional and may be specified to whatever precision is deemed necessary by the transmitting entity.
This format is in general accord with ISO 86015 and the Complete forms defined in W3C Note "Date and Time Formats"
indi_mr.tools.open_redis(redisserver)

Opens a redis connection, return None on failure

Parameters

redisserver (namedtuple) – The redis server parameters

Returns

A redis connection, or None on failure

Return type

redis.client.Redis

Reading values

indi_mr.tools.getproperties_timestamp(rconn, redisserver, name='', device='')
Return the timestamp string when the last getProperties command was sent

by the client, with the given optional device and property name Returns None if not available

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – Optional property name

  • device (String) – Optional device name

Returns

A string of timestamp

Return type

String

indi_mr.tools.last_message(rconn, redisserver, device='')

Return the last message or None if not available

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • device (String) – If given, the device to which the message pertains.

Returns

A string of timestamp space message text.

Return type

String

indi_mr.tools.devices(rconn, redisserver)

Returns a list of devices.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

Returns

A list of device name strings, sorted in name order

Return type

List

indi_mr.tools.properties(rconn, redisserver, device)

Returns a list of property names for the given device.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • device (String) – The device name

Returns

A list of property name strings, sorted in name order

Return type

List

indi_mr.tools.elements(rconn, redisserver, name, device)

Returns a list of element names for the given property and device sorted by element names

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

Returns

A list of element name strings, sorted in name order

Return type

List

indi_mr.tools.attributes_dict(rconn, redisserver, name, device)

Returns a dictionary of attributes for the given property and device

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

Returns

A dictionary of property attributes

Return type

Dict

A description of property attributes is given at Property Attributes.

indi_mr.tools.elements_dict(rconn, redisserver, elementname, name, device)

Returns a dictionary of element attributes for the given element, property and device

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • elementname (String) – The element name

  • name (String) – The property name

  • device (String) – The device name

Returns

A dictionary of element attributes

Return type

Dict

A description of element attributes is given at Element Attributes.

indi_mr.tools.property_elements(rconn, redisserver, name, device)

Returns a list of dictionaries of element attributes for the given property and device each dictionary will be set in the list in order of label

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

Returns

A list of element attributes dictionaries.

Return type

List

Reading logs

This function reads logs from the logdata key stores. See Stored logged values.

indi_mr.tools.logs(rconn, redisserver, number, *keys)

Return the number of logs as [[timestamp,data], …] or empty list if none available where timestamp is the time at which data is received, and data is a list or dictionary of the data logged. The first item in the list is the latest item received.

The keys positional arguments define where the logs are sourced, so if just the literal string “devices” the logs will come from “logdata:devices”, if arguments are ‘elementattributes’, elementname, propertyname, devicename where elementattributes is a literal string and the other values are the actual names, then logs will come from redis store “logdata:elementattributes:<elementname>:<propertyname>:<devicename>”

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • number (Integer) – The number of logs to return

  • keys (Positional arguments) – Defines which redis key is the source of the logs.

Returns

A list of lists, inner lists being [timestamp string, data list or dictionary]

Return type

List

Sending values

The following functions create the XML elements, and uses redis to publish the XML on the to_indi_channel. This is picked up by the inditoredis or other functions (which subscribe to the to_indi_channel), and which then transmits the xml on to indisserver or to MQTT.

indi_mr.tools.getProperties(rconn, redisserver, name='', device='')

Publishes a getProperties request on the to_indi_channel. If device and name are not specified this is a general request for all devices and properties.

If device only is given then this is a request for all properties of that device, if device and name is given, this requests an update for that property of the given device. If name is given, device must also be given.

Return the xml string sent, or None on failure.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – If given, should be the property name.

  • device (String) – If given, should be the device name.

Returns

A string of the xml published, or None on failure

Return type

String

indi_mr.tools.newswitchvector(rconn, redisserver, name, device, values, timestamp=None)

Sends a newSwitchVector request, returns the xml string sent, or None on failure. Values should be a dictionary of element name:state where state is On or Off. Timestamp should be a datetime object, if None the current utc datetime will be used.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

  • values (Dict) – Dictionary of {element name:state, … }

  • timestamp (datetime.datetime) – A datetime.datetime object or None

Returns

A string of the xml published, or None on failure

Return type

String

indi_mr.tools.newtextvector(rconn, redisserver, name, device, values, timestamp=None)

Sends a newTextVector request, returns the xml string sent, or None on failure. Values should be a dictionary of element names : text values. Timestamp should be a datetime object, if None the current utc datetime will be used.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

  • values (Dict) – Dictionary of {element name:new text, … }

  • timestamp (datetime.datetime) – A datetime.datetime object or None

Returns

A string of the xml published, or None on failure

Return type

String

indi_mr.tools.newnumbervector(rconn, redisserver, name, device, values, timestamp=None)

Sends a newNumberVector request, returns the xml string sent, or None on failure. Values should be a dictionary of element names : numeric values. Timestamp should be a datetime object, if None the current utc datetime will be used.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

  • values (Dict) – Dictionary of {element name:new number, … }

  • timestamp (datetime.datetime) – A datetime.datetime object or None

Returns

A string of the xml published, or None on failure

Return type

String

indi_mr.tools.newblobvector(rconn, redisserver, name, device, values, timestamp=None)

Sends a newBLOBVector request, returns the xml string sent, or None on failure. Values should be a list of dictionaries, each dictionary with key of name, size, format, value. The name key should contain the element name, size: number of bytes in the uncompressed BLOB, format: a file suffix, value: the data as bytes, but not base64 encoded, this function will do that. Timestamp should be a datetime object, if None the current utc datetime will be used.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – The property name

  • device (String) – The device name

  • values (List) – List of element dictionaries

  • timestamp (datetime.datetime) – A datetime.datetime object or None

Returns

A string of the xml published, or None on failure

Return type

String

indi_mr.tools.enableblob(rconn, redisserver, name, device, instruction)

Sends an enableBLOB instruction, returns the xml string sent, or None on failure, instruction should be one of Never, Also or Only.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

  • name (String) – Property name, if empty applies to all properties

  • device (String) – The device name

  • instruction (String) – One of Never, Also or Only

Returns

A string of the xml published, or None on failure

Return type

String

Utilities

indi_mr.tools.number_to_float(value)

The INDI spec allows a number of different number formats, given any, this returns a float

Parameters

value (String) – A number string of a float, integer or sexagesimal

Returns

The number as a float

Return type

Float

indi_mr.tools.format_number(value, indi_format)

This takes a float, and returns a formatted string

Parameters
  • value (Float) – A float to be formatted

  • indi_format (String) – An INDI number format string

Returns

The number formatted accordingly

Return type

String

indi_mr.tools.clearredis(rconn, redisserver)

Deletes the redis keys, (not logs) returns None.

Parameters
  • rconn (redis.client.Redis) – A redis connection

  • redisserver (namedtuple) – The redis server parameters

The clearredis function is called when inditoredis is started, and deletes current redis keys, but not the logdata keys.

clearredis does not delete the BLOBs folder or contents.