Legrand / Raritan / Server Technology Xerus™ JSON-RPC API

Loading...
Searching...
No Matches
Event Service

A large number of IDL-defined interfaces define events to notify client applications about changed data (sensor readings, updated settings, etc.). Changes are pushed from the server to the client without need for frequent polling. This allows to write client application that respond quickly to changes; for instance the web GUI makes heavy use of this feature.

Note
  This section is not about configuring event rules and actions! See Event Rules and Actions instead.

# Push Mechanism

The event service uses a so-called long polling technique to emulate a push mechanism. Clients invoke the pollEvents() method to get new events. The server delays the handling of this request for up to 30 seconds as long as no new events are availble. The request is immediately completed as soon as events become available, allowing the client to respond without delay.

Long polling is particularly useful for applications that support handling multiple requests in parallel, either by using asynchronous response handling or multithreading. If this is not possible, clients can use the non-blocking variant pollEventsNb(), which returns immediately even when no events are available. The client must call this method frequently to get new events, which is still better than individually polling a large number of objects.

# Programming Model

Events are distributed by the event.Service instance at `/eventservice`. Clients need to register an event channel, which is their own server-side queue for pending events. Event channels must be actively used to be kept alive. Event channels that are not accessed for 30 seconds are destroyed to reclaim server memory.

After registering an event channel, the client uses the demandEvent and cancelEvent family of methods to configure a filter for events they are interested in. Events can be selected based on type (e.g. numeric sensor reading change) and/or originating object (e.g. the inlet current sensor). Subscriptions can be added and removed at any time as long as the event channel is alive.

Finally, the client repeatedly calls the pollEvents method to get new events. The request completes as soon as new events become available that match one of the client's subscriptions, or after a maximum wait time of 30 seconds.

# Event Definitions

Supported events and their contained data fields are defined in IDL as a hierarchy of `valueobject` declaration. The root event type is `raritan.rpc.idl.Event`, all other events are derived from that type.

All events have a source data field that contains a reference to the object originating the event. E.g., the source of an Outlet.StateChangedEvent is the outlet whose state has changed. Most events declare additional data fields, in this case the old and new outlet state.

Subscriptions for a base event type include derived types. For instance, each of the AccountAdded, AccountRenamed and AccountRemoved events in the UserManager interface extend the base AccountEvent. A client subscribing for this base event will receive add, rename and remove events.

# Python example: Blocking event poll
import raritan.rpc.event
import raritan.rpc.sensors
event_service = raritan.rpc.event.Service("/eventservice", agent)
# Register an event channel
channel = event_service.createChannel()
# Subscribe for reading/state updates from any sensor
channel.demandEventTypes([
raritan.rpc.sensors.NumericSensor.ReadingChangedEvent,
raritan.rpc.sensors.StateSensor.StateChangedEvent
])
# Poll for events until interrupted
print("Polling for events, Ctrl-C to stop ...")
try:
while True:
result, events = channel.pollEvents()
for event in events:
print(event)
except KeyboardInterrupt:
print("\n")