Skip to content

Agent activation

Agent activation is binding you agent to the Watcher. In order to bind, the Agent needs to know operator ID (i.e. Watcher ID) which it uses to request connection data from Flussonic activation server. Operator ID can be built into the Agent or received during the activation process:

  • If the Agent already knows which Watcher it should connect with (i.e. it has Operator ID), then it will automatically activate via Flussonic activation server and the activation server will send required data to Agent and Watcher (or billing system). In this case it does not make a difference if you use Watcher mobile app/web UI or your own app/UI.

  • If the camera has a generic Agent, i.e. the Agent does not know which Watcher it belongs to, and you use Watcher mobile app or web UI, then the app or web UI will provide this info to the Agent when you add a camera. After that the Agent will send request to Flussonic activation server and the activation server will send required data to Agent and Watcher (or billing system).

  • If the camera has a generic Agent 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.

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

Caution

Use only x-vsaas-session key in the request. See API request authorization ways for details on the key types. The request will not be executed with any other key.

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.

Danger

If the camera has already been added, re-adding with the same token may cause errors.

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. In this case the Agent will automatically re-activate.