Device Provisioning APIs

Owned by Editor (Unlicensed)
Last updated: May 18, 2020 by Sarfraz Akram
21 min read

Overview

Documentation of all APIs related to device provisioning (BluFi and Beacon).  Covers everything from basic error handling and session management to device updates and configuration.

BluFI

The BluFi provisioning process is tracked by a transaction.  The client must be authenticated and must provide the credentials in the form of HTTP Cookie for each api request.  The Provisioning process consists of the client initiating a transaction by binding the device sid64, projectId, and Blufi configuration templateId to the transaction.  This is done via a convenience method in "Begin Transaction".  The transaction tracks the state transitions during the provisioning process.  At any point, the client can request transaction status, reset the transaction, or close the transaction.  If the transaction does not complete within a specified amount of time (time TBD), the transaction state will be set to TIMEOUT and closed.  Optionally, the client can provide Tags and DeviceSelfie.

Beacon

Beacon provisioning is completely handling by the Cloud.  The App interaction is for registering the Beacon with the Cloud and associating it with a project.  Once registered, the App may query the cloud for beacon status and update meta-data about the Beacon (name, latitude, longitude, altitude, floor number, tags, etc).

Error Handling

The Cloud is configured for generic and global error handling.  BluZone leverages standard HTTP Status codes as well as some custom extensions.  

Status CodeDescription
200Success
204Success with no content
302Redirect. Client should redirect to the value found in the Location header
401, 403Invalid Access - Client should re-authenticate and try again.
404Resource not found - likely that client is using a bad or old URI
480BluZone custom error (see below)
500Server error - error occurred outside of the global exception handling, perhaps at the application server level.
502The server is down - probably restarting

Custom BluZone Errors

An HTTP Response status of 480 indicates that the client should parse a custom error message.  The Content-Type should be "application/json", and there should be some additional headers added to the response.  

The Client is expected to map the "type" field to a platform specific resource bundle for i18n support.  The array of args should be merged into the template value to provide a rich error messaging experience to the end user.  Since some automated clients (or remote B2B systems) may not support i18n (or JSON parsing), the error code and default rendered message are placed in the response headers.  

It is critical that the Client inspect the http response codes for each API call.

Example Error Message

Content-Type: application/json
X-BZ-Error: ERROR_ACCOUNT_001
X-BZ-ErrorMessage: Username [admin] or email [admin@example.com] already exists.
{
  "code": 500,
  "type": "ERROR_ACCOUNT_001",
  "message": "Username [{0}] or email [{1}] already exists.",
  "args": ["admin", "admin@example.com"],
  "debugMessage": "<only-when-system-in-debug-mode>",
  "debugStack"", "<exception-stack-trace-in-debug-mode>",
  "timestamp", 1234566770
}

System Messages

The BluZone Cloud supports a simple mechanism for alerting remote clients and users of system messages.  The primary use case is to alert a remote user of pending system outages.  The Client is expected to globally inspect responses and handle the "X-BZ-SysMsg" header.  Any api call to the system may result in the "X-BZ-SysMsg" header being set in the response.  It is the responsibility of the client to parse the value of that header and present it to the end user.

Transaction Status Values

  • CONNECT
  • DISCONNECT
  • CANCELED

Session Management

Authentication

REQUEST

POST https://<host>/portal/auth/slogin 
Accept: application/json
Content-Type: application/json
{
  "username": "user@example.com", 
  "password": "mysecret"
}

RESPONSE

NOTE:  This response includes the "projectId" and "projectName" fields.  In the near future, this API will be expanded to include a list of projectId/projectName tuples.  A user account may be a member of multiple Projects.  In that case, the user will need to select a project to be in context.

HTTP/1.x 200 OK
Content-Type: application/json
Set-Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;Version=1;Path=/
{ 
  "username":"myusername",
  "email": "user@example.com",
  "projectId":12345,
  "projectName":"My Project",
  "authToken":"bad18eba1ff45jk7858b8ae88a77fa30",
  "appVersion": {
    "name": "Provisioning App",
    "versionString": "Version 1.13 Build 1650",
    "version": 1.13,
    "build": 1650,
    "updateRequired": true,
    "url": "https://dev.bluvision.com/api/v1/download_link/i52uV4s_9RD4bGNY37tRAQ"
  }
}

Session Ping

This API performs a "get but don't touch" operation on the session.

REQUEST

GET https://<host>/portal/pub/v1/session
Accept: application/json

RESPONSE (Success - Session is still valid)

HTTP/1.x 204 OK

RESPONSE (Failure - Session is NOT valid)

HTTP/1.x 401 Not Authorized

Get Blufi Templates

REQUEST 

The client needs to present a list of Blufi Templates (FKA Wifi Profile configurations) to the user and let the user select which profile Template to use for the provisioning.  The Provisioning API requires a wifiProfileId templateId to be provided at transaction start time.

GET https://<host>/portal/sapis/v1/provisioning/blufiTemplates
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type:  application/json
[
  {
    "templateId": 21,
    "name": "Wifi Profile 1",
    "description": "My Description 1"
  },
  {
    "templateId": 22,
    "name": "Wifi Profile 2",
    "description": "Another Wifi Profile
  }
]

Project Management

The following APIs enable the remote client to browse Projects that the currently signed-in user is able to manage.  The user may either be the owner or a team-member.  The APIs enable fetching a list of projects for the given user and setting a project in context.  All cloud operations expect a project to be set in context.  IMPORTANT:  Switching Projects in the presentation layer MUST be accompanied by an API call to set the project in session context.

NOTE:  Project management APIs are shared from the Portal APIs.  Take care in setting the appropriate API Root:  /papis/v1 rather than /sapis/v1.

Get Available Projects

REQUEST 

The Client may wish to present a list of projects that are enabled for the user.  A list is presented at authentication time, but this API enables the remote client to query for the most up-to-date list.

GET https://<host>/portal/papis/v1/projects
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE 

HTTP/1.x 200 OK
Content-Type: application/json
[
  {
    "projectId": 1,
    "name": "My Project", 
    "description": "Miami Integration",
    "status": "ACTIVE",
    "owner": {
         "username": "robert",
         "emailAddress": "robert@bluvision.com"
         }
  },
  {
    "projectId": 2,
    "name": "Another Project", 
    "description": "Special Integration",
    "status": "ACTIVE",
    "owner": {
         "username": "robert",
         "emailAddress": "robert@bluvision.com"
         }
  }
]

Set Project Context

To switch projects, the remote client must call this API.

REQUEST 

The Client may wish to present a list of projects that are enabled for the user.  A list is presented at authentication time, but this API enables the remote client to query for the most up-to-date list.

NOTE:  The use the target project id value in the URL as replacement for "{projectId}".

This API call will return a 404 error if the user is not associated with the target project.

PUT https://<host>/portal/papis/v1/projects/{projectId}/_set
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE 

HTTP/1.x 200 OK
Content-Type: application/json
{
  "projectId": 2,
  "name": "Another Project", 
  "description": "Special Integration",
  "status": "ACTIVE",
  "owner": {
       "username": "robert",
       "emailAddress": "robert@bluvision.com"
       }
}

Tag Management

Tags are a way to apply arbitrary - user defined categorization to different entities in the system.  We currently support tags for Beacons and will soon add support for BluFis.  Tags are user defined and are scoped to a Project.  Tag values can not be longer than 20 characters.

Sample Tag

{
  "tagId": 1234,
  "value": "My Tag"
}

Tag Query

The system exposes an API to query for existing tags for the project in context.  By default, the query will return all tags.  It is the responsibility of the client to specify the query and wild card (wild card character is the percent character %).  A typical query string would look like ?value="My%" to return all tags that begin with "My".  Sending no query string defaults to "?value="%".  If the query returns an empty set, there are no tags matching that criteria.

NOTE:  The root path for this API is NOT the same as the others.  Take care to use /papis/ instead of /sapis/.

REQUEST 

GET https://<host>/portal/papis/v1/tags?value="My%"
Accept: */*
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
[
  {"tagId": 1, "value": "My First Tag"},
  {"tagId": 2, "value": "My Second Tag"}
]

Tag Associations

Entities that support tags will contain an array of tag objects in the JSON.  To associate a tag with an entity, simply update the entity with the new tag added to the list.  To remove a tag relationship, remove the tag from the list and update the entity.

When updating an entity with tags, the system will automatically create the Tag if it does not already exist.  It is not necessary to explicitly create the Tag before associating it to the entity.

IMPORTANT:  If a Tag already exists, the Client MUST include the "tagId" with the entity.  If not, the system will view this as a duplicate tag and return an error.

Get Blufi Template Tags

Device configuration is template driven.  Templates can be configured with Tags that will automatically get applied to the device being configured with the template.  Once a template has been selected, the user shall be provided an opportunity to edit the default tag selection.  It is the responsibility of the Client App to fetch the tags associated with a given template, and present them to the user.

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/blufiTemplates/{templateId}/tags
Accept: */*
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
[
  {"tagId": 1, "value": "My First Tag"},
  {"tagId": 2, "value": "My Second Tag"}
]

Get Beacon Template Tags

BeaconTemplates also support Tags.  Again, it is the responsibility of the Client App to fetch the list of Tags for the selected Template and present them to the user. 

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/beaconTemplates/{templateId}/tags
Accept: */*
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
[
  {"tagId": 1, "value": "My First Tag"},
  {"tagId": 2, "value": "My Second Tag"}
]

Tag Associations

Entities that support tags will contain an array of tag objects in the JSON.  To associate a tag with an entity, simply update the entity with the new tag added to the list.  To remove a tag relationship, remove the tag from the list and update the entity.

When updating an entity with tags, the system will automatically create the Tag if it does not already exist.  It is not necessary to explicitly create the Tag before associating it to the entity.

IMPORTANT:  If a Tag already exists, the Client MUST include the "tagId" with the entity.  If not, the system will view this as a duplicate tag and return an error.

Device Selfies

Device Selfies are images captured in the wild for deployed devices.  This aids in the location of fielded devices for operations teams.  The system enables the client to associate an image with either a Beacon or a Device.  It is expected that the client will resize the image to the dimensions of 500x500.  Most common image types are supported, but the client must send the appropriate Content-Type value.  The API supports an "offsetX" and "offsetY" attributes that indicate where the device is relative to the image.  An optional "offsetRadius" attribute can be sent for the portal to render a circle around the area.

Device Selfies are supported by both Beacons and BluFis.  There are device type specific APIs for associating a Selfie to a given device.  Those APIs will be detailed in each device type section.  This section provides an overview of what the Selfie API looks like, and how it should be used.

All Selfies are scoped to a project and to a device.  The projectId setting is implied, and the cloud will use the projectId currently set in scope.  By necessity, this would be the same projectId as the Device to which the Selfie references.

API Structure

  • "selfieId":  Is the unique identifier of the selfie and is auto-generated by the server.  Any value placed there when creating a new image will be ignored.
  • "url":  This value is generated by the server on image creation.  The client shall use this value to access the actual binary image.
  • "data":  This value is only populated by the client on CREATE and UPDATE.  The cloud will not return the binary contents within the API.  The value must be Base64 encoded.

Device Selfie JSON Example

{
  "selfieId": 12345,
  "name": "My Beacon Image",
  "contentType": "image/png",
  "overlayX": 20.2,
  "overlayY": 22.1,
  "overlayRadius": 20.0,
  "data": "{base-64-encoded-byte-array}",
  "url": "/portal/papis/v1/selfies/12345/_view"
}

View A Beacon Selfie

NOTE:  The root path for this API is NOT the same as the others.  Take care to use /papis/ instead of /sapis/.  The beacon.seflie.url property defines the URL to access the Selfie image.  It follows the pattern of /papis/v1/projects/{projectId}/devices/beacons/{deviceId}/selfie/_view

REQUEST 

GET https://<host>/portal/papis/v1/projects/{projectId}/devices/beacons/{deviceId}/selfie/_view
Accept: */*
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

REQUEST (Alternate API - Selfie Id based)

GET https://<host>/portal/papis/v1/selfies/{1234}/_view
Accept: */*
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: image/png
[{binary-data}]

BluFi Provisioning Transaction

Start Transaction

REQUEST

POST https://<host>/portal/sapis/v1/provisioning/transactions
Accept: application/json
Content-Type: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{ 
  "gid":"1234556890",
  "templateId": 123456790,
  "altitude": 133.3,
  "blufi": true,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "name": "Friendly Name",
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ]
}

RESPONSE 

HTTP/1.x 200 OK
Content-Type: application/json
{ 
  "transactionId": 12345,
  "projectId":1234567890, 
  "status": "CONNECT", //"disconnect" is sent if not valid gid and device already provisioned
  "blufi": true,
  "device": {
 			 "gid": 1234556890,
             "name": "My BluFi",
             "tags": [...],
 			 "model": "BluFi Lipstic",
  			 "version": "1.4",
 			 "projectId": 1234567890,
 			 "projectName": "My Project",
             "altitude": 133.3,
             "latitude": 26.062861,
             "longitude": -80.186163,
             "floorNumber": 1,
 			 "status": "PROVISIONED",
 			 "dateCreated": "...",
 			 "dateUpdated": "..."
			}
}

Get Transaction Status

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/transactions/{transactionId} 
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE 

HTTP/1.x 200 OK
Content-Type: application/json
{
  "transactionId": 12345,
  "projectId": 12345,
  "gid": 1234556890,
  "templateId": 12345,
  "status": "CONNECT",
  "error" : "Optional Error Message." //Error if any during the provisioning process
}

Setup Provisioning

REQUEST

Command Response is the response from a previous command sent to the BluFi.  It can be empty.

POST https://<host>/portal/sapis/v1/provisioning/transactions/{transactionId}/setup
Accept: application/json
Content-Type: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
    "commandIds" : ["<commandId_1>", "<commandId_2>", <"commandId_3">...],
    "commandResponses": ["<response1>", "<response2>", "<response3>"...]
}

RESPONSE

Initial set of commands that are not encrypted.

HTTP/1.x 200 OK
Content-Type: application/json
{
  "gid": 1234556890,
  "commands": ["<command>", "<command>", "<command>"...],
  "status":"provisioning status",
  "error":"Optional Error Message if a command failed."
}

Ack Command

REQUEST

For every command sent from the Cloud to Blufi via the mobile app an Ack call is made.

POST https://<host>/portal/sapis/v1/provisioning/transactions/{transactionId}/ack/{seq}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "gid": 1234556890,
  "seq": [3, 4, 5, 6, ...]
}

RESPONSE

Encrypted Provisioning Commands

HTTP/1.x 200 OK
Content-Type: application/json
{
  "gid": 1234556890,
  "seq": [3, 4, 5, 6, ...]
}

Get Transaction Encryption Status

REQUEST

GET https://<host>/portal/sapis/v1/provisioning/transactions/{transactionId}/status
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type:  application/json
{
  "transactionId": 12345,
  "gid": "1234",
  "code": "NONE | DONE | STAGE_MONITOR | STAGE_X | ENCR_DONE | ENCR_START | CONNECTED",
  "error": "<message-if-error-case or None>".
  "wifiState" : "NONE | WAITING | CONNECTING | CONNECTED",
  "wsState" : "NONE | CONNECTING | CONNECTED"
}

Cancel Provisioning Transaction

REQUEST

PUT https://<host>/portal/sapis/v1/provisioning/transactions/{transactionId}/cancel
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "transactionId": 12345,
  "projectId":12345,
  "status": "CANCEL"
}

Get Device Status 

Deprecated.  Use /portal/sapis/v1/provisioning/blufis/{gid} instead.  Query will return the same data.

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/devices/{gid} Accept: application/json Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK Content-Type: application/json 
{ 
  "gid": 1234556890, 
  "model": "BluFi Lipstic", 
  "version": "1.4", 
  "projectId": 1234567890, 
  "projectName": "My Project", 
  "status": "PROVISIONED", 
  "altitude": 133.3, 
  "latitude": 26.062861, 
  "longitude": -80.186163, 
  "floorNumber": 1, 
  "name": "Friendly Name", 
  "tags": [ 
    {"tagId": 1, "value": "My Blufi" }, 
    {"tagId": 2, "value": "My Devices" }, 
    {"value": "Deployment 1"} 
  ], 
  "dateCreated": "...", 
  "dateUpdated": "...", 
  "dateProvisioned": "..." 
}

BluFI Management

Exposes REST APIs for managing BluFi.  These APIs enable a Remote Client to perform the same management options on a BluFi meta-data as the portal.  Common use case scenario would be to set/modify the friendly name, or update location info.

Get BluFI

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/blufis/{sid64}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
	"deviceId": 123,
	"projectId": 1234,
	"name": "My BluFI Device",
	"status": "CONNECTED",
	"firmware": {
		"firmwareId": 1234,
		"type": "snf",
		"version": 355,
		"deviceType": {
			"deviceTypeId": 2,
			"name": "SNF Extend",
			"code": "SNF_EXTEND",
			"active": true
		}
	},
	"deviceType": {
		"deviceTypeId": 2,
		"name": "SNF Extend",
		"code": "SNF_EXTEND",
		"active": true
	},
    "tags": [
       {"tagId": 1, "value": "My Blufi" },
       {"tagId": 2, "value": "My Devices" },
       {"value": "Deployment 1"}
    ]
	"altitude": 133.3,
	"latitude": 26.062861,
	"longitude": -80.186163,
	"floorNumber": 1,
	"mainFirmwareRev": 6,
	"bleFirmwareRev": 355,
    "selfie": {
      "selfieId": 12345,
      "name": "My Beacon Image",
      "contentType": "image/png",
      "overlayX": 20.2,
      "overlayY": 22.1,
      "overlayRadius": 20.0,
      "url": "/portal/papis/v1/projects/1234/devices/blufis/1234556890/selfie/_view"
	},
	"sid64": "2550587646590592695",
	"sid128": "",
	"bleMac": "502884484965451",
	"ipAddress": "192.168.4.124",
	"gwAddress": "192.168.4.1",
	"dnsAddress": "192.168.4.1",
	"cloudAddress": "779511140",
	"macAddress": "101366563625312",
	"wifiSsid": "apfelnet"
}

Update BluFI

NOTE:  The API will accept all fields, but only the fields shown here are editable.

REQUEST 

PUT https://<host>/portal/sapis/v1/provisioning/blufis/{sid64}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
	"name": "My BluFI Device",
	"altitude": 133.3,
	"latitude": 26.062861,
	"longitude": -80.186163,
	"floorNumber": 1,
    "tags": [
       {"tagId": 1, "value": "My Blufi" },
       {"tagId": 2, "value": "My Devices" },
       {"value": "Deployment 1"}
    ],
    "selfie": {
      "selfieId": 12345,
      "name": "My Beacon Image",
      "contentType": "image/png",
      "overlayX": 20.2,
      "overlayY": 22.1,
      "overlayRadius": 20.0,
      "url": "/portal/papis/v1/projects/1234/devices/blufis/1234556890/selfie/_view"
    }
}

Notes:

  • Altitude is a float, and represents height above WGS84 ellipsoid
  • Latitude is a double:  valid range -90.0, 90.0
  • Longitude is a double:  valid range -180.0, 180.0

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
	"deviceId": 123,
	"projectId": 1234,
	"name": "My BluFI Device",
	"status": "CONNECTED",
	"firmware": {
		"firmwareId": 1234,
		"type": "snf",
		"version": 355,
		"deviceType": {
			"deviceTypeId": 2,
			"name": "SNF Extend",
			"code": "SNF_EXTEND",
			"active": true
		}
	},
	"deviceType": {
		"deviceTypeId": 2,
		"name": "SNF Extend",
		"code": "SNF_EXTEND",
		"active": true
	},
    "tags": [
       {"tagId": 1, "value": "My Blufi" },
       {"tagId": 2, "value": "My Devices" },
       {"value": "Deployment 1"}
    ],
    "selfie": {
      "selfieId": 12345,
      "name": "My Beacon Image",
      "contentType": "image/png",
      "overlayX": 20.2,
      "overlayY": 22.1,
      "overlayRadius": 20.0,
      "url": "/portal/papis/v1/projects/1234/devices/blufis/1234556890/selfie/_view"
    }
	"altitude": 133.3,
	"latitude": 26.062861,
	"longitude": -80.186163,
	"floorNumber": 1,
	"mainFirmwareRev": 6,
	"bleFirmwareRev": 355,
	"sid64": "2550587646590592695",
	"sid128": "",
	"bleMac": "502884484965451",
	"ipAddress": "192.168.4.124",
	"gwAddress": "192.168.4.1",
	"dnsAddress": "192.168.4.1",
	"cloudAddress": "779511140",
	"macAddress": "101366563625312",
	"wifiSsid": "apfelnet"
}

Beacon Management

Exposes REST APIs for joining a Beacon to a Project via the Provisioning App.

The section covering Beacon APIs assumes a project is in scope.  The cloud will default to a project for the user if one is not explicitly selected.  The current procedure is to take the last logged in project.  It is expected that the client app will select a Project (thus setting it in scope in the cloud).  All calls to the Beacon APIs will use the project in context.  

Registering a Beacon requires that the client provide some some meta-data about the beacon along with a reference to a Device Template (configuration template).  

  1. Scan for device and obtain id64 value (beaconId)
  2. Query the cloud to discover meta-data about this beacon (specifically device type and whether or not this beacon is eligible for configuration/registration)
  3. Query the cloud to obtain a list of DeviceTemplates for a particular Project and DeviceType (by deviceType.deviceTypeId).
  4. Prompt the user to select a template and to provide any other information
  5. Push beacon meta data and deviceTemplateId to the Cloud
  6. Query the cloud for beacon data to obtain status as it moves through provisioning process

Get Beacon

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/beacons/{beaconId}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "beaconId": 1234556890,
  "projectId": 1234,
  "name": "My Beacon 1",
  "status": "NEW",
  "managerType": "APP", // [APP|CLOUD]
  "templateId": null,
  "firmware": {
    "firmwareId": 1234,
    "type": "snf",
    "version": 355,
    "deviceType": {
        "deviceTypeId": 2,
        "name": "SNF Extend",
        "code": "SNF_EXTEND",
        "active": true
    }
  },
  "deviceType": {
    "deviceTypeId": 2,
    "name": "SNF Extend",
    "code": "SNF_EXTEND",
    "active": true
  },
  "selfie": {
      "selfieId": 12345,
      "name": "My Beacon Image",
      "contentType": "image/png",
      "overlayX": 20.2,
      "overlayY": 22.1,
      "overlayRadius": 20.0,
      "url": "/portal/papis/v1/projects/1234/devices/beacons/1234556890/selfie/_view"
  },
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dynamicUrl": "http://bluvision.com",
  "dateProvisioned": 12345678,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Get Beacon Strongest Signal

Beacon <-> Blufi range is important for deployment. In order to ensure a successful deployment we provide the ability to request the signal strengths of beacons to the blufi environment.

It's possible to send a single beacon sid or mulitple sid's:

REQUEST

POST https://<host>/portal/sapis/v1/provisioning/beacons/signal
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "deviceIds":["12345678","90123456","78901234",...]
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "devices":[{"id" : "12345678", "signal" : ["NONE | WEAK | MEDIUM | STRONG", "rssi" : "value"},
             {"id" : "90123456", "signal" : ["NONE | WEAK | MEDIUM | STRONG", "rssi" : "value"},
             {"id" : "78901234", "signal" : ["NONE | WEAK | MEDIUM | STRONG", "rssi" : "value"}, ...]
}


Get Device Templates

Device Templates are scoped to a project and a DeviceType.  Device Templates are user defined so there can be many per DeviceType.  As a convenience, the system automatically creates a default template for device type when the project is first created.

Once a particular Beacon has been selected, the client can query for any available templates.  The cloud will first verify that the Beacon is not scoped under another project.  If so, a 404 error will be returned.

If the Beacon has never been provisioned before, the Cloud will attempt to locate the device type from the manufacturing data based on the deviceId (id64).  

An empty array will be returned if there are no DeviceTemplates for the associated device type, or if the device is not found in the manufacturing database.

REQUEST

GET https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/templates
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
[
  {
    "templateId": 1,
    "name": "East Wing",
    "description": "Medium power"
  },
  {
    "templateId": 2,
    "name": "Generic Waypoint",
    "description": "Waypoint beacon for my deployment"
  }
]

Register Beacon

REQUEST 

POST https://<host>/portal/sapis/v1/provisioning/beacons
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "deviceId": "1234556890",
  "name": "Optional arbitrary name",
  "templateId": 1234,
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "selfie": {
    "name": "My Beacon Image",
    "contentType": "image/png",
    "overlayX": 20.2,
    "overlayY": 22.1,
    "overlayRadius": 20.0,
    "data": "{base_64_encoded_data}"
  }
}

Notes:

  • Altitude is a float, and represents height above WGS84 ellipsoid
  • Latitude is a double:  valid range -90.0, 90.0
  • Longitude is a double:  valid range -180.0, 180.0

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "deviceId": 1234556890,
  "projectId": 1234,
  "name": "My Beacon 1",
  "status": "NEW",
  "managerType": "CLOUD",
  "templateId": 1234,
  "firmware": {
    "firmwareId": 1234,
    "type": "snf",
    "version": 355,
    "deviceType": {
        "deviceTypeId": 2,
        "name": "SNF Extend",
        "code": "SNF_EXTEND",
        "active": true
    }
  },
  "deviceType": {
    "deviceTypeId": 2,
    "name": "SNF Extend",
    "code": "SNF_EXTEND",
    "active": true
  },
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "selfie": {
    "selfieId": 12345,
    "name": "My Beacon Image",
    "contentType": "image/png",
    "overlayX": 20.2,
    "overlayY": 22.1,
    "overlayRadius": 20.0,
    "url": "/portal/papis/v1/projects/1234/devices/beacons/1234556890/selfie/_view"
  },
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dynamicUrl": "http://bluvision.com",
  "dateProvisioned": 12345678,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Update Beacon

REQUEST 

NOTE:  The deviceId value is the Beacon's id64 value, as a String.

PUT https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "deviceId": "1234556890", 
  "name": "Optional arbitrary name",
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "tags": [...],
  "selfie": {...}
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "deviceId": 1234556890,
  "projectId": 1234,
  "name": "My Beacon 1",
  "status": "NEW",
  "managerType": "APP",
  "templateId": 1234,
  "firmware": {
    "firmwareId": 1234,
    "type": "snf",
    "version": 355,
    "deviceType": {
        "deviceTypeId": 2,
        "name": "SNF Extend",
        "code": "SNF_EXTEND",
        "active": true
    }
  },
  "deviceType": {
    "deviceTypeId": 2,
    "name": "SNF Extend",
    "code": "SNF_EXTEND",
    "active": true
  },
  "selfie": {
    "selfieId": 12345,
    "name": "My Beacon Image",
    "contentType": "image/png",
    "overlayX": 20.2,
    "overlayY": 22.1,
    "overlayRadius": 20.0,
    "url": "/portal/papis/v1/selfies/12345/_view"
  },
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dynamicUrl": "http://bluvision.com",
  "dateProvisioned": 12345678,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Add Beacon Selfie

A client may submit one or more Selfies of the Beacon "In the Wild".  This helps field operation teams locate beacons.  The App supports capturing a picture of the area, and optionally adding coordinates of the beacon location within the image.

REQUEST 

Uploads and associates a Device Selfie with a Beacon.

POST https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "name": "Optional selfie name",
  "contentType": "image/png",
  "overlayX": 25.23,
  "overlayY": 24.22,
  "overlayRadius": 20.1,
  "data": {base-64-encoded-binary-data}
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234567890,
  "deviceId": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}

Update A Beacon Selfie

Change the beacon selfie data.

REQUEST 

PUT https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "name": "Optional image name",
  "contentType": "image/png",
  "overlayX": 25.23,
  "overlayY": 24.22,
  "overlayRadius": 20.1,
  "data": {base-64-encoded-binary-data}
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234556890,
  "deviceId": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}

Delete A Beacon Selfie

REQUEST 

DELETE https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 204 OK

Fetch A Beacon Selfie (meta-data)

Change the beacon Selfie.

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234556890,
  "deviceId": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}

Third-Party Device Management

Exposes REST APIs for joining a third party device (cloud adapter or beacon) to a Project.

The section covering Third-party device management assumes a project is in scope.  The cloud will default to a project for the user if one is not explicitly selected.  The current procedure is to take the last logged in project.  It is expected that the client app will select a Project (thus setting it in scope in the cloud).  All calls to the Third-Party Device APIs will use the project in context.  

Registering Third-Party Devices is simply a matter of associating the third-party device UUID with a project and optionally setting the device location in the cloud.

Register a Device

Registering a device results in a device_uuid being generated for that device. Subsequent calls related to this device should always reference this device_uuid.

Note: "type:adapter" below sets this device as a cloud adapter and "type:beacon" sets this device as a beacon.

REQUEST 

POST https://<host>/portal/sapis/v1/provisioning/device
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "name": "Optional arbitrary name",
  "type": "adapter", 
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "tags": [
     {"tagId": 1, "value": "My Device" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ]
  "meta-data": [ 
     <any-valid-json-name-value-pairs>
  ]
}

Notes:

  • Altitude is a float, and represents height above WGS84 ellipsoid
  • Latitude is a double:  valid range -90.0, 90.0
  • Longitude is a double:  valid range -180.0, 180.0

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "device_uuid": 1234556890,
  "projectId": 1234,
  "name": "My Cloud Adapter",
  "status": "NEW",
  "tags": [
     {"tagId": 1, "value": "My Cloud Adapter" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "meta-data": [ 
	 <valid-json-name-value-pairs>
  ],
  "selfies": [],
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Get Third-Party Device

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/device/{uuid}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "device_uuid": 1234556890,
  "projectId": 1234,
  "name": "My Adapter 1",
  "status": "NEW",
  "type": "adapter",
  "selfies": [
    {
      "selfieId": 12345,
      "name": "My Beacon Image",
      "contentType": "image/png",
      "overlayX": 20.2,
      "overlayY": 22.1,
      "overlayRadius": 20.0,
      "url": "/portal/papis/v1/selfies/12345/_view"
    }
  ],
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "meta-data": [ 
	 <any-valid-json-name-value-pairs>

  ],
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Update Third-Party Device

REQUEST 

NOTE:  The adapter_uuid value is the Device's uuid, as a String.

PUT https://<host>/portal/sapis/v1/provisioning/adapter/{adapter_uuid}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "adapter_uuid": "1234556890", 
  "name": "Optional arbitrary name",
  "type": "adapter",
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "meta-data": [ 
	 <valid-json-name-value-pairs>

  ]
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "deviceId": 1234556890,
  "projectId": 1234,
  "name": "My Cloud Adapter",
  "status": "NEW",
  "type": "adapter",
  
  "selfie": {
    "selfieId": 12345,
    "name": "My Beacon Image",
    "contentType": "image/png",
    "overlayX": 20.2,
    "overlayY": 22.1,
    "overlayRadius": 20.0,
    "url": "/portal/papis/v1/selfies/12345/_view"
  },
  "tags": [
     {"tagId": 1, "value": "My Blufi" },
     {"tagId": 2, "value": "My Devices" },
     {"value": "Deployment 1"}
  ],
  "altitude": 133.3,
  "latitude": 26.062861,
  "longitude": -80.186163,
  "floorNumber": 1,
  "dateCreated": 12345678,
  "dateUpdated": 12345678
}

Add Third-Party Device Selfie

A user may submit one or more Selfies of the Device "In the Wild".  This helps field operation teams locate devices.  

REQUEST 

Uploads and associates an Device Selfie with a Device.

POST https://<host>/portal/sapis/v1/provisioning/devices/{device_uuid}/selfies
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "name": "Optional image name",
  "contentType": "image/png",
  "overlayX": 25.23,
  "overlayY": 24.22,
  "overlayRadius": 20.1,
  "data": {base-64-encoded-binary-data}
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234567890,
  "deviceId": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}

Update a Device Selfie

Change the beacon Selfie.

REQUEST 

PUT https://<host>/portal/sapis/v1/provisioning/devices/{device_uuid}/selfies/{selfieId}
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;
{
  "name": "Optional image name",
  "contentType": "image/png",
  "overlayX": 25.23,
  "overlayY": 24.22,
  "overlayRadius": 20.1,
  "data": {base-64-encoded-binary-data}
}

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234556890,
  "deviceId": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}

Delete A Device Selfie

REQUEST 

DELETE https://<host>/portal/sapis/v1/provisioning/devices/{device_uuid}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 204 OK

Fetch A Device Selfie (meta-data)

Change the device Selfie.

REQUEST 

GET https://<host>/portal/sapis/v1/provisioning/beacons/{deviceId}/selfie
Accept: application/json
Cookie: X-BZ-AuthToken=bad18eba1ff45jk7858b8ae88a77fa30;

RESPONSE

HTTP/1.x 200 OK
Content-Type: application/json
{
  "selfieId": 1234556890,
  "device_uuid": 1234,
  "name": "My Beacon Image 1",
  "contentType": "image/png",
  "url": "/portal/papis/v1/selfies/1234567890/_view"
}