Messaging Interface

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
      }
  }