Protocol Description - SukkoPera/Arduino-Sensoria GitHub Wiki

Sensoria is a simple protocol based on the exchange of single lines of text between a client and a server.

The general usage pattern consists in a client sending a server a single-line text message containing a command. The server evaluates the command and replies with a single-line text reply.

Commands consist of 3-letter words. Commands MUST be in upper case, but clients SHOULD be able to interpret commands in a case-insensitive manner.

All lines MUST be terminated with a single CR character.

• Command:

    <command> [args]
  

• Invalid command reply:

    ERR [reason]
  

  This reply MUST be sent when the server does not understand the command at all, for instance when an unsupported command is sent. The reason is optional and, if not specified, it is assumed to be Unsupported command.

• Successful command reply:

    <command> OK [args]
  

  This reply MUST be sent when the server has evaluated a command correctly. Arguments are optional and dependent on the specific command that was evaluated.

• Failed command reply:

    <command> ERR [reason]
  

  This reply MUST be sent when the server has correctly recognized a command but it has encountered an error during the evaluation of the command, which overall failed. A detailed failure reason can be provided in the reply (e.g.: Invalid parameters, Sensor error, etc...).

Request node information, i.e.: name and transducer list. This command can also be sent to the broadcast address, all servers must reply in this case.

• Request: HLO

• Reply: HLO <node_name> <protocol_version> (<name> <type> <stereotype> [description])|...

• Example:

    <-- HLO
    --> HLO Outdoor-1 1 OT S WD|OH S WD|OP S WD
  

protocol_version is a number optionally followed by capital letters stating the protocol version and options the node is speaking. The only defined protocol version is 1, at the moment. No options are defined yet.

A list of transducers follows the protocol version. For every transducer, its name, type and stereotype are reported, following by an optional description. name is an alphanumeric string composed of two characters, case-insensitive. type is either S for sensors or A for actuators. stereotype follows the same rules as name. description is optional and can contain spaces. None of these fields can contain the pipe character |, which is used to separate data for different transducers.

Note that this command does not follow the general rules, as neither OK nor ERR are specified in the reply. This is because this command cannot fail and is always successful.

Read a transducer.

• Request: REA <transducer_name>

• Reply: REA (OK <data>|ERR [reason])

• Examples:

    <-- REA OH
    --> REA OK T:11.00 H:40.00
  
    <-- REA TT
    --> REA ERR No such transducer
  

Data reported in the reply MUST be formatted according to the stereotype the transducer conforms to, which is reported in the reply to the HLO command.

Write to an actuator. Sensors cannot be written to.

• Request: WRI <actuator_name> <data>

• Reply: WRI (OK [data]|ERR [reason])

• Examples:

    <-- WRI RH ON
    --> WRI OK ON
  
    <-- WRI RB OFF
    --> WRI ERR No such actuator
  

In case of a positive reply, data representing the new actuator state MAY be included in the reply, to save the client from issuing a read. If present, such data MUST be formatted according to the stereotype the actuator conforms to, which is reported in the reply to the HLO command.

Configure a setting on a transducer.

Not yet implemented

Issue a Notification Request.

• Request: NRQ <transducer_name> <notification_type> [args]

  notification_type can either be PRD for periodic notifications or CHA in order to be notified when the specified transducer changes value (what this means exactly is defined in the stereotype the transducer conforms to). In the former case, args MUST be an integer, representing the desired interval in seconds between notifications.

• Examples:

    <-- NRQ OT CHA
    --> NRQ OK
  
    <-- NRQ OT PRD 60
    --> NRQ OK
  

This command is optional and, if supported, the NDL command MUST be supported as well.

Delete a Notification Request.

• Request: NDL <transducer_name> <notification_type>

• Examples:

    <-- NDL OT CHA
    --> NDL OK
  

This command also supports a special form:

    <-- NDL ALL
    --> NDL OK

This deletes all notification requests that were issued from the client sending the command. Useful on application close, for instance.

This command is optional and, if supported, the NRQ command MUST be supported as well.

Clear all notification requests.

• Request: NCL

• Examples:

    <-- NCL
    --> NCL OK
  

This deletes all notification requests that were issued from all clients. It is a sort of emergency command, not meant to be used in ordinary functioning.

This command is optional.

Reset the server.

• Request: RST

• Examples:

    <-- RST
    --> RST OK
  

This makes the server perform a self-reset and return to normal operation.

This command is optional.

Shutdown server.

• Request: DIE

• Examples:

    <-- DIE
    --> DIE OK
  

This makes the server perform a shutdown and stop responding to client requests until it is manually restarted.

This command is optional.

Notification.

• Syntax: NOT <data>

• Examples:

    --> NOT T:11.00 H:40.00
  

Notifications report data upon verification of the conditions specified in the Notification Requests (i.e.: periodically or on change). Data MUST be formatted according to the stereotype the transducer conforms to, which is reported in the reply to the HLO command.

Server advertisement.

Not yet implemented