parlay.protocols

parlay.protocols.base_protocol

class parlay.protocols.base_protocol.BaseProtocol[source]

Bases: object

This the base protocol that all parlay protocols must inherit from. Subclass this to make custom protocols to talk to 3rd party equipment.

close()[source]

Override this with a generic method that will close the protocol.

e.g. @classmethod def close():

get_discovery()[source]

This will get called when a discovery message is sent out. Return a deferred that will be called back with all attached: item types, message types, and connected item instances

get_new_data_wait_handler()[source]
classmethod get_open_params()[source]

Returns the params for the cls.open() class method. Feel free to overwrite this in a sub-class if this default implementation doesn’t fit your protocol’s needs. :return: A list of parameter names :rtype: list

classmethod get_open_params_defaults()[source]

return the defaults for parameters to the cls.open() using inspect. Feel free to overwrite this in a sub-class if this default implementation doesn’t fit your protocol’s needs. :return: A dictionary of parameter names -> default values. :rtype: dict

get_protocol_discovery_meta_info()[source]

This will return protocol meta-info that will be returned with every discovery message. This is a good place to store things like enuemrations or protocol status to pass to the UI

got_new_data(*args, **kwargs)[source]

Call this when you have new data and want to pass it to any waiting Items

classmethod open(adapter)[source]

Override this with a generic method that will open the protocol. The first argument must be the broker, the rest will be parameters that the user can set. Default arguments will be sent to the UI and can be overwritten bu the user It must return the built protocol (subclass of Protocol) that will be registered with the Broker Be sure to decorate it with @classmethod

e.g. @classmethod def open(cls, adapter, ip, port=8080):

return protocol(ip,port)
class parlay.protocols.base_protocol.WaitHandler(deferred)[source]

Bases: object

An Object used to do safe cross thread waits on deferreds

addCallback(*args, **kwargs)[source]

Add a callback when you get new data

wait(*args, **kwargs)[source]

Call this to wait until there is data from the protocol. If threaded: Will block. Return value is serial line data If Async : Will not block. Return value is Deferred that will be called back with data :param timeout_secs : Timeout if you don’t get data in time. None if no timeout :type timeout_secs : int|None

parlay.protocols.local_item

The Local Item protocol lets you open arbitrary items that have been registered as local

class parlay.protocols.local_item.LocalItemProtocol(item)[source]

Bases: parlay.protocols.base_protocol.BaseProtocol

ID = 0
class TransportStub[source]

Bases: object

Fake transport that will allow the protocol to think its writing to a transport

write(payload)[source]
classmethod LocalItemProtocol.close()[source]
classmethod LocalItemProtocol.get_open_params_defaults()[source]
classmethod LocalItemProtocol.open(broker, item_name)[source]
classmethod LocalItemProtocol.open_for_obj(item_obj)[source]
parlay.protocols.local_item.auto_start()[source]

Auto start local items that have that flag set

parlay.protocols.local_item.local_item(auto_connect=False)[source]

A class decorator for python Items that are not part of an external protocol.

Local items are self-contained, and do not communicate over external protocols, for example a serial port. They are typically used for simulators or pure python computation items.

Parameters:auto_connect – whether to automatically connect to the Parlay broker when the item is created.
Returns:decorator function

Example usage of local_item decorator:

# motor_sim.py

@local_item()
class MotorSimulator(ParlayCommandItem):

    def __init__(self, item_id, item_name):
        ...

Example usage of defined local item:

import parlay
from motor_sim import MotorSimulator

MotorSimulator("motor1", "motor 1")  # motor1 will be discoverable
parlay.start()

parlay.protocols.meta_protocol

Define the base Protocol classes and meta-classes.

For documentation on broker and common message types see parlay.protocols:

.. py:exception:: InvalidProtocolDeclaration
module:parlay.protocols.meta_protocol

Bases: exceptions.Exception

Raised when there was a problem with your protocol declaration

class parlay.protocols.meta_protocol.ProtocolMeta(name, bases, dct)[source]

Bases: type

Meta-Class that will keep track of all message types declared Also builds the message field lookups from the Django-model-style message class definitions

protocol_registry = {'LocalItemProtocol': <class 'parlay.protocols.local_item.LocalItemProtocol'>, 'BaseProtocol': <class 'parlay.protocols.base_protocol.BaseProtocol'>}

parlay.protocols.serial_line

class parlay.protocols.serial_line.ASCIILineProtocol(port)[source]

Bases: parlay.protocols.base_protocol.BaseProtocol, twisted.protocols.basic.LineReceiver

When a client connects over a serial, this is the protocol that will handle the communication. The messages are encoded as a JSON string

broker = <parlay.server.broker.Broker object>
close()[source]
classmethod get_open_params_defaults()[source]

Override base class function to show dropdowns for defaults

lineReceived(line)[source]
classmethod open(broker, port='/dev/tty.usbserial-FTAJOUB2', baudrate=57600, delimiter='\n')[source]

This will be called bvy the system to construct and open a new SSCOM_Serial protocol :param cls : The class object (supplied by system) :param broker: current broker insatnce (supplied by system) :param port: the serial port device to use. On linux, something like “/dev/ttyUSB0”. On windows something like “COM0” :param baudrate: baudrate of serial connection :param delimiter:

open_ports = set([])
rawDataReceived(data)[source]
class parlay.protocols.serial_line.LineItem(item_id, name, protocol)[source]

Bases: parlay.items.parlay_standard.ParlayCommandItem

LAST_LINE_RECEIVED = ''
send_raw_data(*args, **kwargs)[source]
wait_for_data(*args, **kwargs)[source]

:type timeout_secs float

parlay.protocols.utils

Generic utilities and helper functions that help make protocol development easier

class parlay.protocols.utils.MessageQueue(callback)[source]

Bases: object

A basic message queue for messages that need to be acknowledged

add(message)[source]

Add a message to the queue self.waiting_for_ack_seq_num = None # None = not waiting ... an int here, It will be sent in FIFO order

:returns A deferred that will be called back (or err-backed) when the message is done processing :rtype defer.deferred

class parlay.protocols.utils.PrivateDeferred(canceller=None)[source]

Bases: twisted.internet.defer.Deferred

A Private Deferred is like a normal deferred, except that it can be passed around and callbacks can be attached by anone, but callback() and errback() have been overridden to throw an exception. the private _callback() and _errback() must be used

This ensures that only a user that ‘knows what their doing’ can issue the callback

callback(result)[source]
errback(fail=None)[source]
exception parlay.protocols.utils.TimeoutError[source]

Bases: exceptions.Exception

parlay.protocols.utils.delay(seconds)[source]
Parameters:seconds
Returns:
parlay.protocols.utils.message_id_generator(radix, minimum=0)[source]

makes an infinite iterator that will be modulo radix

parlay.protocols.utils.timeout(d, seconds)[source]

Call d’s errback if it hasn’t been called back within ‘seconds’ number of seconds If ‘seconds’ is None, then do nothing

parlay.protocols.websocket

class parlay.protocols.websocket.WebSocketServerAdapter(broker=None)[source]

Bases: autobahn.twisted.websocket.WebSocketServerProtocol, parlay.server.adapter.Adapter

When a client connects over a websocket, this is the protocol that will handle the communication. The messages are encoded as a JSON string

broker = <parlay.server.broker.Broker object>
discover(force)[source]
get_open_protocols()[source]
get_protocols()[source]

Return a list of protocols that could potentially be opened. Return a deferred if this is not ready yet

onClose(wasClean, code, reason)[source]
onConnect(request)[source]
onMessage(payload, isBinary)[source]
send_message_as_JSON(msg)[source]

Send a message dictionary as JSON

class parlay.protocols.websocket.WebsocketClientAdapter[source]

Bases: parlay.server.adapter.Adapter, autobahn.twisted.websocket.WebSocketClientProtocol

Connect a Python item to the Broker over a Websocket

call_on_every_message(listener)[source]
onConnect(request)[source]
onMessage(packet, isBinary)[source]

We got a message. See who wants to process it.

publish(msg, callback=None)[source]
subscribe(_fn=None, **topics)[source]

Subscribe to messages the topics in **kwargs

class parlay.protocols.websocket.WebsocketClientAdapterFactory(*args, **kwargs)[source]

Bases: autobahn.twisted.websocket.WebSocketClientFactory

buildProtocol(addr)[source]