gadgets.gadget

Gadget

class gadgets.gadget.Gadget(location, name, addresses, timeout=None)

The components that run in the gadgets system should be a subclass of Gadget.

After a gadget starts and registers, it listens for zmq messages that are specified by the events attribute. (see the gadgets.sockets module for more details). After a message is received the ‘event_received’ method is called.

There are many possible uses of Gadget subclasses. One of the main subclasses built into Gadgets is Device. It is meant for controlling physical devices. A Gadget subclass isn’t just for interfacing with hardware. For example, here is a class that records all of the goings on of the system:

>>> class Recorder(Gadget):

... @property ... def events(self): ... return [‘UPDATE’] ... ... def event_received(self, event, message): ... with open(‘/tmp/gadgets_data.txt’, ‘a’) as buf: ... buf.write(json.dumps(message) + ‘

‘)

It would probably better to make one that saves the messages to a database.

In order to make a Gadgets subclass, you must define an events property and implement event_received. The event_received will only receive messages that you specified in the events property.

do_shutdown()

override this if your subclass needs to do more stuff in order to shutdown cleanly.

event_received(event, message)

receives the events defined by self.events

events

Returns a list of events that will trigger the event_received method

on_start()

override this if you need to do something before the main loop starts

status

Device overrides this property to indicate weather or not the Device is turned on

uid

A gadget uid us composed of the location and name properties. No two Gadget instances should have the same uid.

gadgets.coordinator

Coordinator

class gadgets.coordinator.Coordinator(addresses, name)

The Coordinator keeps track of the state of all the gadgets and provides a few ways for gadgets to request information. Coordinator listens for the following events (this defines the zmq-based API for gadgets):

register: When a gadget starts up it sends a register message.

The register message just lets the Coordinator know that there is a new Gadget. If the Gadget is a Device then the register message also includes the commands that turn the device on and off.

>>> sockets.send('register', {
        'location': '<some location>',
        'name': '<some name>',
        'on': '<some on event>',
        'off': '<some off event>',    
    })

method: A method is a list of RCL messages. If Coordinator

receives a method message it starts up an instance of MethodRunner which then executes the method.

>>> sockets.send('method', {
        'method': [
            'turn on living room light',
            'wait for 1 hour',
            'turn off living room light'
        ]
    })

update: Whenever a Gadget reaches some new state, it should

send an update message. The Coordinator reads the message and updates its _state attribute. The _state attribute is accessible to the outside world via the status message (see status below). After Coordinator receives an update event, it sends an UPDATE event that contains the _state dict. The UPDATE event is intended for GUIs. Whenever something changes a GUI would want to be immediately notified.

>>> sockets.send('update', {
        '<some location>': {
            '<some name>': {
                'value': True
           }
       }
   })

status: Send a status message and the response is the _state dict

of the Coordinator. Do with that state what you will. The message should contain the id of the entity that sent the request.

>>> sockets.send('status', {
        'id': '<some unique id>'
    })
>>> _id, status = sockets.recv()

events: This message is also a request. The response is all the

on and off events that the Coordinator knows of due to gadgets registering and including ‘on’ and ‘off’ in the register message (see register above). This is useful for GUIs to be able to know how to turn things on and off.

>>> sockets.send('events', {
        'id': '<some unique id>'
    })
>>> _id, events = sockets.recv()

locations: Another request that is useful for GUIs. The response

is a list of all the locations in the system that are registered with the Coordinator.

>>> sockets.send('locations', {
        'id': '<some unique id>'
    })
>>> _id, locations = sockets.recv()

shutdown: If this message is sent than all Gadget subclasses

and the Coordinator will exit their main loops and die. This message shuts down the whole system.

>>> sockets.send('shutdown')

error: Any gadget can send this message and it will be stored

in the _state attribute of the Coordinator.

>>> sockets.send('error', {
        'error': '<some error message>'
        'id': '<some unique id>'
    })