Skip to main content

Communicating with the SystemManager

Services should communicate with the mod-SystemManager following its communication protocol and appropriate endpoints. Information for specific exchanges can be found below.

tip

These docs merely exist to support custom service registration and dependency resolution mechanisms. It is highly recommended to use either pkg-ServiceRunner or the mod-ServiceWrapper to handle registration and dependency resolution for you.

Endpoints​

During runtime, the mod-SystemManager exposes two ZeroMQ endpoints:

  • A REQ-REP endpoint to handle service (de)registrations and information requests
  • A PUB-SUB endpoint to broadcast service (de)registrations and new tuning states

The addresses of these endpoints are defined in its service.yaml definition.

Message wrapping and error reporting​

All Protobuf communication messages mentioned on this page should be wrapped in a generic Protobuf SystemManagerMessage. All responses sent by the SystemManager will also be wrapped this way.

Error checking

Always check if the wrapped message is an Error message, as defined here.

Registering a service​

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped Service message.

Request response
The SystemManager will respond with one of the following:

  • A wrapped Service message
    • You should check if the contents of this message match the request content (specifically the service name and PID). If not, teh SystemManager has denied registration because another service is already running with this name.
    • Also check the ServiceStatus field
  • An Error message.

If registration is successful, the SystemManager will broadcast a Service message on the PUB-SUB endpoint, notifying all listening services that a new service was registered.

Updating the status of a service​

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped ServiceListRequest message. Set the ServiceStatus field to the status you want the SystemManager to report to other services. You can leave the PID field of the ServiceIdentifier field empty, as it will not be used by the SystemManager.

Request response
The SystemManager will respond with one of the following:

If the status change was successful, the SystemManager will broadcast a Service message with ServiceStatus set to STOPPED on the PUB-SUB endpoint, notifying all listening services that a service was deregistered.

Requesting information about a registered service​

A service might request information about a different registered service to resolve its dependencies or to check whether or not the other service is still running.

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped ServiceInformationRequest message. You can leave the PID empty, as it will not be used by the SystemManager to look up the service you requested.

Request response
The SystemManager will respond with one of the following:

Requesting a list of all registered services​

A service might request a list of all registered services from the SystemManager. This is done by the mod-DebugTransceiver for example, to find out which services are currently registered.

note

The SystemManager will only send a list of active services. Stopped services will not be present in the list.

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped ServiceListRequest message.

Request response
The SystemManager will respond with one of the following:

Broadcasting a new tuning state​

note

The SystemManager will happily broadcast a tuning state message it receives from any service in your pipeline, but it is not recommended to send tuning states manually. Tuning states are normally sent to the SystemManager by the mod-DebugTransceiver.

Merging states

The SystemManager will try to merge the newly received tuning state with the current tuning state. In this process, it will discard tuning options with types that differ from the types already present in the tuning state.

E.g. if a tuning parameter brightness of type int is present in the current tuning state, a new tuning state parameter brightness with type float will be discarded.

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped TuningState message.

Request response
The SystemManager will respond with one of the following:

If the merge of tuning states was successful, the SystemManager will broadcast the newly merged tuning state on its PUB-SUB endpoint.

Requesting a new tuning state​

Services can request a "fresh copy" of the current tuning state from the SystemManager.

Endpoint to use
Send a request to the REQ-REP endpoint.

Request content
Send a wrapped TuningStateRequest message.

Request response
The SystemManager will respond with one of the following: