Message Broker

This is the server-to-server communication description.

With the server to server API, it is possible to receive (both camera and user) events through a message queue. The messages are JSON encoded and are sent over WebSockets with the STOMP protocol.

Before start using this API, we at CameraManger need to setup and configure the message queue before you can use this. The configuration and some more explanation need to be discussed beforehand.

Event types

Events that are generated by the camera:

  • Audio event
  • Pir event
  • Motion event
  • Clvr events
  • Doorbell event
  • Camera status event

All have the same JSON structure.

Parameter Description
source_id ID of the camera
type Type of the source (camera)
epoch_start_time Epoch time in milliseconds
event_unique_identifier Unique ID of the event

Note: the type of the event must be parsed from the message routing key.

Route key pattern
[true|false].[true].[partner_id].[user_id].[cam_detection|cam_status|].[event_name]

The first two booleans are used for internal routing logic of Cameramanager and can be ignored.

Key pattern Description
partner_id ID of the partner
user_id ID of the user
cam_detection | cam_status Identify if event is of type camera detection or camera status
event_name

In case of cam_detection one of the following values:

  • audio
  • pir
  • motion
  • doorbell
  • object_area
  • object_tripwire
  • person_area
  • person_tripwire

In case of cam_status one of the following values:

  • online
  • offline

Examples:

Camera detection events:

  • PIR event: false.true.1.0.cam_detection.pir
  • Audio event: false.true.1.2.cam_detection.audio
  • Motion event: false.true.1.2.cam_detection.motion
  • Doorbell event: false.true.1.2.cam_detection.doorbell
  • CLVR events:
    • object in area: false.true.1.10.cam_detection.object_area
    • object tripwire: false.true.1.10.cam_detection.object_tripwire
    • person in area: false.true.1.10.cam_detection.person_area
    • person tripwire:false.true .1.10.cam_detection.person_tripwire

Camera state events:

  • Camera available: false.true.1.3.cam_status.online
  • Camera unavailable: false.true.1.3.cam_status.offline

Events that are triggered by user:

  • Camera added                 « user added camera
  • Camera deleted                 « user removed camera
  • Firmware upgrade event         « firmware upgrade
  • Live view requested        « user requested camera live view
  • Rec view requested        « user requested camera footage
  • Configuration change        » user updated camera wifi settings
  • Error event                        « Error event in case one of above action failed


All user action events have common fields:

Parameter Description
user_id ID of the user that triggered the event
type Type of the source (User)
epoch_start_time Epoch time in milliseconds
camera_id ID of the camera
event_unique_identifier Unique ID of the event

Route key pattern
[true|false].[true].[partner_id].[user_id].[user_cam_action|].[event_name]

The first two booleans are used for internal routing logic of CameraManager and can be ignored.

Key pattern Description
partner_id ID of the partner
user_id ID of the user
user_cam_action Used for all user triggered events
event_name

One of the following values:

  • camera_added
  • camera_deleted
  • firmware_upgrade
  • liveview_requested
  • recview_requested
  • camera_wifi_updated
  • error

Examples

User camera action events.

User added camera

  • routing key: false.true.1.3.user_cam_action.camera_added

JSON

User deleted camera:

  • routing key: false.true.1.3.user_cam_action.camera_deleted

JSON


User requested live view

  • routing key: false.true.1.3.user_cam_action.liveview_requested

json: same as user deleted camera

User requested rec view

  • routing key: false.true.1.3.user_cam_action.recview_requested

json: same as user deleted camera

User upgraded the firmware of the camera

  • routing key: false.true.1.3.user_cam_action.firmware_upgrade

JSON



“status” can have the following values:

User updated/set camera wifi settings

  • routing key: false.true.1.3.user_cam_action.camera_wifi_updated

JSON

An error happened during the above actions (except for firmware update errors that are stored in the “status” field)

  • routing key: false.true.1.3.user_cam_action.error

JSON


the “description” field contains the error message and the “action” field is the related         event that failed and can be one of the following:

  • camera_added
  • camera_deleted
  • liveview_requested
  • recview_requested

Description/example


Message consumer connects to the Cameramanager server at IP messages.cameramanager.com using WebSockets protocol and STOMP transport.

The consumer is authenticated by using the partner email and its password to be used in the Authorization header like:

ws://messages.cameramanager.com:2080/stomp/v1

or

wss://messages.cameramanager.com:2443/stomp/v1

Authorization: Basic <partner_email>:<password>

(<partner_email>:<password> should be encoded in Base64)



Communication example on STOMP level:
*Client/message consumer messages are marked by red
*Server/message broker messages are marked by grey
*******************
CONNECT     
accept-version:1.2
heart-beat:30000,60000      <<< setup ping intervals in seconds


.
CONNECTED
session:session-1ft-6Znzeu34Y0bgw9ibaw
heart-beat:60000,30000
version:1.2


.
SUBSCRIBE
destination:/exchange/<exchange_name>/<routing_key>     <<< subscribe to the exchange <exchange_name> for a specific routing key
ack:client                                           <<< client will send explicit acknowledgement message
prefetch-count:1                                <<< number of prefetch messages


.
MESSAGE
destination:/exchange/<exchange_name>/partner.1.2.cam_detection.pir  <<< event of type «pir detection»
message-id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@2
redelivered:false
expiration:120000
content-type:application/json
content-length:87


{"source":{"id":5,"type":"Camera"},"startTime":1452607548372,"duration":0,"uniqueID":31}


ACK
id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@2


MESSAGE
destination:/exchange/<exchange_name>/partner.1.1.cam_detection.audio
message-id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@346
redelivered:false
expiration:120000
content-type:application/json
content-length:88


{"source":{"id":6,"type":"Camera"},"startTime":1452607462681,"duration":0,"uniqueID":15}


ACK
id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@346
*****************


Note:
You can use all possibilities of the stomp protocol
- subscribe to different queues via the same connection
- open simultaneously multiple connections
- control the way of acknowledgement mechanism: auto/client/client-individual (for further information check stomp documentation at https://stomp.github.io/)