Agent activation from your own app

Agent activation is binding your Agent to the Watcher. In order to bind, the Agent needs to know Operator ID which it uses to request connection data from Flussonic activation server. For more details on the Agent operation procedure, see How Flussonic Agent works.

Operator ID can be built into the Agent or received during the activation process. If Operator ID is already built into the Agent by the camera vendor, then no additional actions are required from the developer: activation will be performed automatically when the camera is launched with an unactivated Agent whether you use Watcher mobile app/web UI or your own app/UI.

If the camera has a generic Agent that is not tied to a specific Watcher and you are developing your own app/UI to operate Watcher, then you should implement API to send activation data (like operator ID and authorization token) to the Agent so that it could activate via the activation server. Please see the details below.

It is also possible to make improvements to the firmware of your camera with Agent in order to be able to activate Agent via QR code just like the Iris camera. Read more in the end of this article at Sending the authorization token to the Agent using a QR code.

What is the Agent authorization token?

Authorization token is encrypted information about the camera name, preset and Organization it belongs to. The token serves as a unique identifier for the Agent during the activation process.

The Agent activation process:

1. The app tells Watcher to activate the camera with the given name, organization and preset.
2. Watcher replies with the camera authorization token to the application. After that Watcher will wait for the camera with this exact authorization token to be provisioned.
3. The app communicates the authorization token to the Agent (via QR code or HTTP request).
4. The Agent sends the authorization token to the activation server.
5. The activation server assigns the token with agent_id, agent_key, watcher_url and sends them back to Agent and Watcher/billing together with the authorization token.
6. Watcher checks if the authorization token is known to it and adds the camera to the specified Organization with specified preset.

The first three steps are to be implemented in the app.

Authorization token request

First of all, the app must request an Agent authorization token from Watcher with the following request:

POST YOUR_WATCHER_URL/vsaas/api/v2/agent-activation-tokens

The header should contain x-vsaas-session and content-type: application/json parameters

The JSON request body should include the following parameters:

• "title" — string, the name of the camera with which it will be added to Watcher.
• "organization_id" — integer, identifier of the organization to which the camera will be added.
• "preset_id" — integer, the identifier of the preset with which the camera will be added.

Organizations and presets must have been previously created in Watcher. You can create Organizations and presets as you like, both from the web UI and using the API.

The response will be JSON with "token" string parameter. This is the authorization token that the app should send to the Agent later. The response can also indicate the token validity period (the valid_till parameter).

Example (replace x-vsaas-session to your key)

curl -v POST http://127.0.0.1/vsaas/api/v2/agent-activation-tokens \
-d '{"title": "activateCam", "organization_id": "1", "preset_id": "1"}' \
-H 'x-vsaas-session: j9h2Hxu_o9Gf0TyoPjesLLBkBbc' -H "Content-Type: application/json"

Response

{"token":"MURAELYI","valid_till":0}

Then you need to check whether a camera with this token has already been added:

GET YOUR_WATCHER_URL/vsaas/api/v2/agent-activation-tokens/(token)

Include x-vsaas-session in the header.

The response will be JSON with "camera_name" string parameter. If the token is not yet in use, i.e. no camera is added, the parameter will be null. In this case, you can proceed to activating the Agent by IP address or QR code as described below.

Example (replace x-vsaas-session to your key)

curl -v GET http://127.0.0.1/vsaas/api/v2/agent-activation-tokens/MURAELYI \
-H 'x-vsaas-session: j9h2Hxu_o9Gf0TyoPjesLLBkBbc' -H "Content-Type: application/json"

Response

{"token":"MURAELYI","valid_till":0,"camera_name":null}

Sending the authorization token to the Agent by IP address

After receiving the authorization token and making sure that the camera is not yet added in Watcher, the app must transmit the received data to the Agent. The request is sent to the address of the camera accessible from the app with port 5680:

POST CAMERA_URL:5680/activate

The header should include Content-Type: application/x-www-form-urlencoded;charset=UTF-8. Other formats are not supported.

Request parameters:

• "operatorid" is a unique identifier of the Provider registered on the activation server. You can see it in the Watcher settings on the Mobile applications tab. This identifier never changes so you can hard-code it in your app.
• "sign" is the token received before.
• "abonentid" — subscriber's email address.

Example

curl -v POST http://192.168.1.64:5680/activate \
-d 'operatorid=44766&sign=MURAELYI&abonentid=user.name@mail.com' \
-H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8"

The Agent will response with status 200 and then request the activation server.

Check if the Agent was activated by requesting its status:

CAMERA_URL:5680/agent-status

Such a request will return parameters:

• "version" of the Agent
• "status" of the Agent: "activate" for activated Agent or "wait_activate" for Agent waiting to be activated.
• "serial" number of the camera

Example

curl -v GET http://192.168.1.64:5680/agent-status 

Response

{version: 'v19.05-84-gc4b3544bf', status: 'wait_activate', serial: 'f8f86484c5bf6f327e6de196205e7'}

Sending the authorization token to the Agent using a QR code

Cameras with Agent can be activated by presenting a QR code to the camera. IRIS Wi-Fi cameras are activated by the QR code without any firmware modifications while third-party cameras require additional integration between the developed application and the camera firmware, i.e. the firmware should be modified to receive data from the QR code and transmit them to the Agent configuration file.

The QR code for IRIS cameras is three lines of text:

Wifi_SSID
Wifi_Password
operator_id:token

operator_id is a unique identifier of the Provider registered on the activation server. You can see it in the Watcher settings on the Mobile applications tab. This identifier never changes so you can hard-code it in your app.

Deactivating the Agent

Delete the camera from Watcher to deactivate the Agent.