Device Service - Device Configuration

This document provides guidance on configuring devices to connect with the iotcomms.io platform via the /provisioning/device/{domain} REST API endpoint. It ensures that devices are correctly provisioned, authenticated, and managed within the platform for seamless communication and service access.

SIP (Session Initiation Protocol) is a widely used communication protocol enabling voice and video calls over the Internet. Various device types use SIP, including:

• Care Alarm Devices – Use the SCAIP protocol for alarm event transmission and SIP for VoIP communication with monitoring centers.

• WebRTC Clients – Web applications leveraging WebRTC for media transport and SIP over WebSockets for signaling.

• SIP Phones and Softphones – Hardware or software-based telephony endpoints for voice calls.

• SIP-Based Surveillance Cameras – Used for remote monitoring and security integration.

• Alarmbridge Connect Gateway Devices – Hardware deployed in group living schemes to bridge analog alarm devices with IP-based Alarmbridge Service.

• Devices Behind Group Scheme Controllers – Alarm units managed under centralized control in assisted living and residential care environments.

The iotcomms.io Device Service enables seamless integration and centralized management of these devices, ensuring secure provisioning, authentication, and monitoring.

To enable a SIP device to connect to the iotcomms.io services, it must be properly configured with the necessary credentials and SIP settings. This process can be performed using a device-specific provisioning service, a web-based interface, or manual configuration depending on the device type and deployment model. Each SIP device is assigned a unique SIP address, following the format:

sip:<deviceid>@<domain>

Where <domain> is unique per customer. It is found in the tenant section of the menu when logged in to the developer portal.

Key Configuration Parameters

• Device ID (deviceId) – A unique identifier assigned to each SIP device.

• SIP Address – The address where the device can send and receive SIP requests.

• SIP Server (sipserver) – The SIP proxy server managing connections. Devices should use:

  • sipserver.prod-eu-north-1.iotcomms.io (for EU region)

  • sipserver.prod-us-1.iotcomms.io (for US region)

• Authentication Credentials:

  • Username (deviceId) – Used for authentication if different from the SIP address.

  • Password (password) – Securely stored or transmitted using an HA1 hash.

  • Realm (domain) – Used in authentication challenges to validate the device.

For Alarmbridge Connect Gateway devices and devices behind group scheme controllers, provisioning follows the same process but may require additional configuration to align with group scheme-specific routing and protocol conversion settings for seamless integration with the Alarmbridge Service.

The iotcomms.io platform provides a RESTful provisioning API that allows for automated device provisioning. The main API endpoint is:

1. Create or Update a Device

• Method: PUT

• Endpoint: /provisioning/device/{domain}

• Description: Creates or updates a device within the given domain.

• Request Body:

{
    "deviceId": "device42",
    "authType": "credentials",
    "ha1": "f467e138e35f3570a42399a04762d150",
    "description": "Office Phone",
    "deviceCLI": "1234"
}

• Response Example:

{
    "status": "success",
    "message": "Device provisioned successfully"
}

2. Delete a Device

• Method: DELETE

• Endpoint: /provisioning/device/{domain}/{deviceId}

• Description: Removes a provisioned device from the given domain.

• Response Example:

{
    "status": "success",
    "message": "Device deleted successfully"
}

3. Retrieve Device Information

• Method: GET

• Endpoint: /provisioning/device/{domain}/{deviceId}

• Description: Fetches the configuration details of a provisioned device.

• Response Example:

{
    "deviceId": "device42",
    "authType": "credentials",
    "description": "Office Phone",
    "deviceCLI": "1234"
}

To authenticate a device using a JWT token, the device must first request a token using the authentication API. The following API endpoint is used to fetch a JWT token:

• Method: POST

• Endpoint: /provisioning/authorize/{domain}

• Description: Authenticates the device using its username and password and retrieves a JWT token to be used for SIP request authentication.

• Request Body:

{
    "userId": "device42",
    "password": "supersecret"
}

• Response Example:

{
    "result": true,
    "authorized": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

The received JWT token must be included in the X-JWTAuth SIP header for authentication in subsequent requests.

Devices can also be provisioned using the web interface available at Device Configuration. This interface allows users to create, update, and manage devices without using the API. Bulk device import is supported, making it easy to add multiple devices at once.

The web interface also displays the SIP device registration state in the status column, allowing users to monitor whether a device is successfully registered and connected to the platform.

The iotcomms.io Device Service ensures secure and scalable device provisioning, supporting various authentication methods and configuration models. By leveraging the API-driven provisioning, bulk import functionality, and centralized authentication management, organizations can efficiently deploy and manage SIP-based devices across large-scale communication networks, including Alarmbridge Connect gateways and devices behind group scheme controllers in assisted living environments.