Skip to content

Messaging Interface

simen edited this page May 11, 2017 · 5 revisions

In freebird, the web-Client and Server are communicating with each other through websocket along with a JSON message. The value of __intf field in the message must be be 'REQ', 'RSP' or 'IND' to denote the messaging interface.



Request Message

  • Direction: [C2S] Client sends to Server to request something or to ask the server to perform an operation.

  • Message keys: { __intf, subsys, seq, id, cmd, args }

    Property Type Description
    __intf String 'REQ'
    subsys String Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message going to
    seq Number Sequence number of this REQ/RSP transaction
    id Number Id of the sender. id is meaningless if subsys === 'net'. id is device id if subsys === 'dev'. id is gadget id if subsys === 'gad'. It is noticed that id = 0 is reserved for the freebird web-Client and Server
    cmd String Command Identifier corresponding to the API name
    args Object A value-object that contains command arguments. Please see section Request Data Model to learn more about the args data object
  • Message Example:

    { 
        __intf: 'REQ',
        subsys: 'net',
        seq: 3,
        id: 0,
        cmd: 'getDevs',
        args: {
            ids: [ 2, 4, 18, 61 ]
        }
    }



Response Message

  • Direction: [S2C] Server responds to Client with result of the client asking for.

  • Message keys: { __intf, subsys, seq, id, cmd, status, data }

    Property Type Description
    __intf String 'RSP'
    subsys String Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this message coming from
    seq Number Sequence number of this REQ/RSP transaction
    id Number Id of the sender. id is meaningless if subsys === 'net'. id is device id if subsys === 'dev'. id is gadget id if subsys === 'gad'. It is noticed that id = 0 is reserved for the freebird web-Client and Server
    cmd String Command Identifier corresponding to the API name
    status Number Status code of the response
    data Depends Data along with the response. To learn more about the data format corresponding to each command, please see section Response Data Model.
  • Message Example:

    { 
        __intf: 'RSP',
        subsys: 'net',
        seq: 17,
        id: 0,
        cmd: 'getAllDevIds',
        status: 205,
        data: {
            ids: [ 2, 4, 18, 61 ]
        }
    }



Indication Message

  • Direction: [S2Cs] Server indicates Client(s)

  • Message keys: { __intf, subsys, type, id, data }

    Property Type Description
    __intf String 'IND'
    subsys String Only 3 types accepted. They are 'net', 'dev', and 'gad' to denote which subsystem is this indication coming from
    type String There are few types of indication accepted, such as 'attrsChanged'. Please see section Indication types for details
    id Number Id of the sender. id is meaningless if subsys === 'net'. id is device id if subsys === 'dev'. id is gadget id if subsys === 'gad'
    data Depends Data along with the indication. Please see section Indication Data Model to learn more about the indication data format



Indication types

subsys Indication Type Description
net 'error' Netcore error occurs
net 'started' A netcore is started
net 'stopped' A netcore is stopped
net 'enabled' A netcore is enabled
net 'disabled' A netcore is disabled
net 'permitJoining' A netcore is now allowing devices to join the network
net 'bannedDevIncoming' A banned device is trying to join the network
net 'bannedGadIncoming' A banned gadget is trying to join the network
net 'bannedDevReporting' A banned device is trying to report its attributes
net 'bannedGadReporting' A banned gadget is trying to report its attributes
dev 'error' Device error occurs
dev 'devIncoming' A new device is incoming
dev 'devLeaving' A device is leaving
dev 'netChanged' Network information of a device has changed
dev 'statusChanged' Status of a device has changed. The status can be 'online', 'sleep', 'offline', and 'unknown'
dev 'propsChanged' Meta-property(ies) of a device has changed
dev 'attrsChanged' Attribue(s) on a device has changed
gad 'error' Gadget error occurs
gad 'gadIncoming' A new gadget is incoming
gad 'gadLeaving' A gadget is leaving
gad 'panelChanged' Panel information of a gadget has changed
gad 'propsChanged' Meta-property(ies) of a gadget has changed
gad 'attrsChanged' Attribue(s) on a gadget has changed
gad 'attrsReport' A report message of certain attribute(s) on a gadget
  • Message Example:

    { 
        __intf: 'IND',
        subsys: 'gad',
        type: 'attrsChanged',
        id: 147,            // sender of this indication is a gadget with id = 147
        data: {
            sensorValue: 24
        }
    }