.. _device-discovery-api:

Device Discovery
================

Setting up a new device for consuming the TAG REST API is a four steps process:

1. Log into the Control Room and browse to the **Device > Discovery** page.
2. Open your **TAG app** and scan the QR Code [1]_ you see on that page
3. Enter a unique code [2]_ in your **TAG app** when you are prompted to and hit :guilabel:`Connect`
4. Click on :guilabel:`Add` when you see the unique code you just entered showing up on the **Device Discovery** page

.. [1] The QR Code is nothing more than a URI to the `POST /device-request/new`_ API method that the Satellite Tag app
       will hit to announce itself.

.. [2] Usually the app unique code is the 2-4 digits code on the back of the device. Because this code must be unique
       if you need to use it for multiple apps on the same physical device you must add a suffix (preferred) or prefix
       to it. For example, if ``80`` is the unique code printed on the back and you need two separate apps running on
       the same device, check-in app and access control app, then you could use ``80CHECKIN`` and ``80ACL`` to uniquely
       identify them.

.. mermaid::

  sequenceDiagram

    participant Mobile App
    participant TAG API
    participant Control Room

  Control Room ->> Mobile App: Display QR Code
  Mobile App ->> TAG API: POST /api/v5/device-request/new
  TAG API ->> Control Room: Display request
  Control Room ->> TAG API: Approve request
  TAG API ->> Mobile App: Send OAuth2 credentials
  Mobile App ->> TAG API: POST /api/oauth/v2/token
  TAG API ->> Mobile App: Send OAuth2 access token

  Mobile App ->> TAG API: POST /api/v5/device/ping
  TAG API ->> Mobile App: Send TAG config response

  loop frequency as per config
  Mobile App ->> TAG API: POST /api/v5/device/ping
  TAG API ->> Mobile App: Send TAG config response
  end

POST /device-request/new
------------------------

Sends a new device discovery request to the server. If the request is accepted in the backend the response will expose
API credential and common settings for up to 10 minutes after the request is first accepted.

You must send two parameters with this request, they are both required:

- ``code`` the unique code
- ``secret`` a random secret code

You can also send a ``preferredType`` parameter, specifying the type of your app. This can be project specific, but
some predefined types, recognised by all TAG instances are: ``checkin``, ``accesscontrol`` and ``upload``.

You will get back some useful information, possibly the most useful being ``apiUrl``, that is the base URL you need to
prefix to all API methods documented here.

.. note::

  For this method to work you must log into the backend and browse to the **Device Discovery** page. Every time such
  page is loaded or refreshed the availability of this method is prolonged by 5-10 minutes.

See the list of `Error Responses`_ for more information, in particular errors 1001 and 1002.

.. _Error Responses: /rest_api/index.html#error-responses

Example request:

.. code-block:: json

  {
	"code": "INSOMNIA",
	"secret": "B7HmsMiUbl18Bk3Lx1Yo",
    "preferredType": "accesscontrol"
  }

Example response (before approval):

.. code-block:: json

  {
    "data": {
      "id": 14,
      "code": "INSOMNIA",
      "secret": "B7HmsMiUbl18Bk3Lx1Yo",
      "agent": "insomnia\/2023.5.8",
      "createdAt": "2023-09-27T13:30:50+13:00",
      "updatedAt": "2023-09-27T13:30:50+13:00",
      "apiUrl": "https:\/\/localhost:8000\/api"
	},
    "meta": {}
  }

Example response (after approval):

.. code-block:: json

  {
    "data": {
      "id": 14,
      "code": "INSOMNIA",
      "secret": "B7HmsMiUbl18Bk3Lx1Yo",
      "agent": "insomnia\/2023.5.8",
      "deviceId": 53,
      "clientId": "28b7...20e6",
      "clientSecret": "88ea...0c8b",
      "clearedAt": "2023-09-27T13:31:10+13:00",
      "clearedStatus": "added",
      "createdAt": "2023-09-27T13:30:50+13:00",
      "updatedAt": "2023-09-27T13:31:10+13:00",
      "apiUrl": "https:\/\/localhost:8000\/api"
	},
    "meta": {}
  }

If the unique code you are trying to use has been used already you will get back an error. This error should be shown
back to the user so they can choose a different code. The error will look like this:

.. code-block:: json

  {
	"data": {},
    "meta": {
      "error": {
        "code": 409,
        "message": "This code has been discovered already. Use a different code, or append something to it.",
        "internalCode": 1002
      }
    }
  }

If the device discovery feature is disabled you will get back an error:

.. code-block:: json

  {
    "data": {},
    "meta": {
      "error": {
        "code": 503,
        "message": "Device discovery is not accepting requests at this time. Contact an administrator for help.",
        "internalCode": 1001
      }
    }
  }