Developer
Ask a QuestionBlecon WebsiteBlecon Console
  • Learn Blecon
    • Introduction
    • Blecon Modems
      • Device Identity and Network Security
      • Modem Firmware vs Modem Library
      • Using the Modem
      • Communicating with the cloud
      • Sending data from the cloud to a device
    • Blecon Hotspots
    • Blecon Networks
      • Blecon Accounts
      • Registering devices
        • The Blecon Scanner
        • Blecon Scanner Developer Guide
      • Blecon Events
      • Cloud Integrations
  • Cloud Integrations
    • Webhook
    • AWS S3
    • AWS SQS
    • AWS EventBridge
    • Memfault
  • Getting Started Guides
    • Getting started index
    • Install the Blecon Modem Firmware
    • Set up a Blecon Hotspot
    • Use Blecon from your computer with the Blecon CLI
    • Create a Network and register a device
    • Send device requests and events to your web service
    • Use Blecon from a Development Board
    • Use the Blecon Modem from an MCU
  • Device Guides
    • KKM S5-BCN
  • Development Board Guides
    • Supported Development Boards
    • Ezurio DVK-BL54L15
    • Fanstel EV-BM15C
    • InsightSiP ISP2454-LX-EB
    • Nordic nRF52840DK
    • Nordic nRF54L15DK
    • Minew ME54BE01
    • Panasonic PAN-B511 EVB
    • Raytac AN54L15Q-DB
    • u-Blox EVK-NORA-B20
  • Modem Reference
    • Modem Firmware Releases
      • nRF54L15 DK
      • nRF52840 Dongle
      • nRF52840 DK
    • CLI Releases
    • SDK Releases
    • Modem API Reference
    • Modem Protocol Reference
      • Request Frames
      • Command Protocol
      • UART Transport
    • Guides and best practices
      • Retrieve a device's identity
  • Cloud Reference
    • Configuration API
    • Advanced event routing
  • Hotspot Reference
    • Blecon Hub
Powered by GitBook

Get Support

  • Ask a question
On this page
  • Using the Blecon Scanner
  • Overview of operation
  • Blecon Scanner API
  1. Learn Blecon
  2. Blecon Networks
  3. Registering devices

Blecon Scanner Developer Guide

Programatically obtain Blecon Device IDs using the Blecon Scanner

PreviousThe Blecon ScannerNextBlecon Events

Last updated 4 months ago

There are a number of scenarios where an application may need to obtain the device ID of a Blecon device. These include:

  • Initial registration of the device to your organisation’s Blecon network

  • Associating a device ID with that of a customer account

  • Accessing or updating information about a device in the field given its device ID

Your application can take advantage of the Blecon Scanner to scan for and obtain device IDs without you having to implement custom scanning functionality.

Using the Blecon Scanner

The Blecon Scanner, which is included in Blecon’s mobile (iOS and Android) apps, allows external mobile apps and websites to programmatically request scans for Blecon devices and will return the ID of a device that the user has picked.

Overview of operation

To use the Blecon Scanner, mobile apps or web applications on the mobile device open the Blecon Scanner URL along with specific configuration parameters that include a callback URL (i.e., a webhook), to which the results of a scan will be returned.

Opening the Blecon Scanner URL launches the Blecon Scanner on the mobile device. The Blecon Scanner prompts a user to scan a Blecon device. When the user successfully selects a device (or cancels the operation), the Blecon Scanner passes the ID of the selected device back to the application by opening the supplied callback URL.

Example showing Blecon Console webapp launching the Scanner

Blecon Scanner API

Launch the Blecon Scanner by opening the following URL and passing the callback parameter:

https://blecon.app/scanner?callback=<callbackURL>

Where callbackURL is an URL template which is a URL containing variable substitution expressions such as {device_id}, which the Blecon Scanner will replace with information that is collected when the Blecon Scanner is run. The URL that results after substitutions have been made is the location where Blecon Scanner should redirect the user once scanning is completed. The URL can be that of a website or a Universal Link (iOS) or App Link (Android) that launches an application on the device.

Example

To specify that the Blecon Scanner should open https://www.example.org such that ID of the device the user selects in the scanner is passed back in the device_id parameter of the querystring, the application would use the following URL template:

https://www.example.org?device_id={device_id}

The application must URL encode the URL template and pass it in under the callback querystring parameter when opening the Blecon Scanner URL. Thus, the link to launch the scanner, with the URL-encoded callback is:

https://blecon.app/scanner?callback=https%3A%2F%2Fwww.example.org%3Fdevice_id%3D%7Bdevice_id%7D

If the device scanned has ID 123e4567-e89b-12d3-a456-426655440000, the Blecon Scanner will redirect the user to https://www.example.org?device_id=123e4567-e89b-12d3-a456-426655440000and if no device was detected or the scanner was cancelled the Blecon Scanner will open https://www.example.org?device_id=None


Supported Parameters when Launching the Scanner

Parameter
Description

callback

Location to return the user to after scanning has completed. Required

Supported variables in URL templates

Variable
Description

device_id

Selected device ID or “None” if no device was selected.

Additional examples of how to construct the callback URL

The above example demonstrated passing back the selected device ID as a querystring parameter. However, the URL template can be used to create other formats for the callback URL.

For instance:

  • Including the device ID as part of the URL path, e.g.: https://www.example.org/{device_id}/

  • Including additional data (e.g., unique session identifier, authorization token, etc.) alongside the returned data, e.g.: https://www.example.org/register?&data=foo&device_id={device_id}

The Blecon Console uses the Blecon Scanner API to collect Device IDs to register Blecon Devices onto a network