--- # API Explorer Source: https://help.1nce.com/api/ # Welcome to the 1NCE API :::warning 'Try It' Feature Please note that the 'Try It' function can be used only with a valid 1NCE customer account. All queries are made towards the customer account. Be careful with trying out features like orders, top ups, etc. as these API calls will trigger the actual process. ::: Welcome to the 1NCE API documentation. This documentation covers the ins and outs of the API for managing, controlling, and monitoring the 1NCE SIM cards and the related services. This guide is divided into chapters, which group individual, logical topics together. As the 1NCE API requires users to authorize in order to use the interface, we strongly suggest starting with the authorization chapters first. The API is structured into different categories: - **Authorization** - Authentication and token management - **SIM Management** - SIM card operations and monitoring - **Order Management** - Order placement and tracking - **Product Information** - Product catalog and details - **Support Management** - Support ticket management - **1NCE OS** - 1NCE Operating System APIs These groups are created according to the features of the 1NCE products. Besides documenting the functionality of the possible API requests, this guide offers the opportunity for existing customers to try out the calls with their personal 1NCE account. As an additional feature, the guide offers ready-to-use code snippets for each query in a wide variety of programming languages. These samples ease the transition from testing out the API to integrating the interfaces into an automated production environment. If there are any issues or questions regarding the 1NCE services, feel free to contact our [technical support](https://1nce.com/en-eu/support/contact). --- # 1NCE OS Source: https://help.1nce.com/api/1nce-os/1-nce-os/ Documentation of the 1NCE OS API which can be used for managing the 1NCE OS Service. - [Accept 1NCE OS Agreements](/api/1nce-os/accept-1-nce-os-agreements/) - [Cancel all device action requests](/api/1nce-os/cancel-all-device-action-requests/) - [Cancel single device action request](/api/1nce-os/cancel-single-device-action-request/) - [Create Action Request for the LwM2M Device](/api/1nce-os/create-action-request-for-the-lw-m-2-m-device/) - [Create Action Request On Specific CoAP Device.](/api/1nce-os/create-action-request-on-specific-co-ap-device/) - [Create Action Request On Specific LwM2M Device](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/) - [Create Action Request On Specific UDP Device.](/api/1nce-os/create-action-request-on-specific-udp-device/) - [Create Action Requests for CoAP Devices.](/api/1nce-os/create-action-requests-for-co-ap-devices/) - [Create Action Requests for LwM2M Devices.](/api/1nce-os/create-action-requests-for-lw-m-2-m-devices/) - [Create Action Requests for UDP Devices.](/api/1nce-os/create-action-requests-for-udp-devices/) - [Create AWS Integration](/api/1nce-os/create-aws-integration/) - [Create geofence](/api/1nce-os/create-geofence/) - [Create Optimizer Template](/api/1nce-os/create-optimizer-template/) - [Create Pre-Shared Device Key](/api/1nce-os/create-pre-shared-device-key/) - [Create Pre-shared Key for the Device](/api/1nce-os/create-pre-shared-key-for-the-device/) - [Create Webhook Integration](/api/1nce-os/create-webhook-integration/) - [Delete geofence](/api/1nce-os/delete-geofence/) - [Delete Integration](/api/1nce-os/delete-integration/) - [Delete Optimizer Template](/api/1nce-os/delete-optimizer-template/) - [Disable ADL device location settings](/api/1nce-os/disable-adl-device-location-settings/) - [Enable ADL device location settings](/api/1nce-os/enable-adl-device-location-settings/) - [Get a geofence](/api/1nce-os/get-a-geofence/) - [Get a list of plugin installations](/api/1nce-os/get-a-list-of-plugin-installations/) - [Get active device action requests](/api/1nce-os/get-active-device-action-requests/) - [Get Administration Log Payload](/api/1nce-os/get-administration-log-payload/) - [Get Administration Logs Statistics](/api/1nce-os/get-administration-logs-statistics/) - [Get Administration Logs](/api/1nce-os/get-administration-logs/) - [Get All Customer Integrations](/api/1nce-os/get-all-customer-integrations/) - [Get All Devices](/api/1nce-os/get-all-devices/) - [Get all geofences](/api/1nce-os/get-all-geofences/) - [Get archived device action requests](/api/1nce-os/get-archived-device-action-requests/) - [Get CloudFormation Parameters](/api/1nce-os/get-cloud-formation-parameters/) - [Get Customer Integration](/api/1nce-os/get-customer-integration/) - [Get customer settings](/api/1nce-os/get-customer-settings/) - [Get details about a specific plugin installation](/api/1nce-os/get-details-about-a-specific-plugin-installation/) - [Get device action requests](/api/1nce-os/get-device-action-requests/) - [Get Device Celltower location resolutions](/api/1nce-os/get-device-celltower-location-resolutions/) - [Get device endpoints](/api/1nce-os/get-device-endpoints/) - [Get Device Historian Insights](/api/1nce-os/get-device-historian-insights/) - [Get Device Historian Messages](/api/1nce-os/get-device-historian-messages/) - [Get Device Positions](/api/1nce-os/get-device-positions/) - [Get Device Telemetry](/api/1nce-os/get-device-telemetry/) - [Get Devices Statistics](/api/1nce-os/get-devices-statistics/) - [Get Historian Insights](/api/1nce-os/get-historian-insights/) - [Get Historian Messages](/api/1nce-os/get-historian-messages/) - [Get Integration Event Types](/api/1nce-os/get-integration-event-types/) - [Get Latest Devices Positions](/api/1nce-os/get-latest-devices-positions/) - [Get Optimizer Templates](/api/1nce-os/get-optimizer-templates/) - [Get per-device settings](/api/1nce-os/get-per-device-settings/) - [Get Pre-Shared Device Key](/api/1nce-os/get-pre-shared-device-key/) - [Get Pre-Shared Keys Import Job Status](/api/1nce-os/get-pre-shared-keys-import-job-status/) - [Get savings](/api/1nce-os/get-savings/) - [Get single device action request](/api/1nce-os/get-single-device-action-request/) - [Get single device endpoint](/api/1nce-os/get-single-device-endpoint/) - [Get Single Device](/api/1nce-os/get-single-device/) - [Import Pre-Shared Keys for Devices](/api/1nce-os/import-pre-shared-keys-for-devices/) - [Import Pre-Shared Keys for the Devices](/api/1nce-os/import-pre-shared-keys-for-the-devices/) - [Install Datacake plugin for 1NCE OS](/api/1nce-os/install-datacake-plugin-for-1-nce-os/) - [Install Memfault plugin for 1NCE OS](/api/1nce-os/install-memfault-plugin-for-1-nce-os/) - [Install Mender plugin for 1NCE OS](/api/1nce-os/install-mender-plugin-for-1-nce-os/) - [Install Tartabit plugin for 1NCE OS](/api/1nce-os/install-tartabit-plugin-for-1-nce-os/) - [Patch a geofence](/api/1nce-os/patch-a-geofence/) - [Patch Customer Integration](/api/1nce-os/patch-customer-integration/) - [Patch Customer Webhook Integration](/api/1nce-os/patch-customer-webhook-integration/) - [Patch Setting Details](/api/1nce-os/patch-setting-details/) - [Patch Settings](/api/1nce-os/patch-settings/) - [Patch single device endpoint](/api/1nce-os/patch-single-device-endpoint/) - [Pre-Shared Devices Keys Import Job Status](/api/1nce-os/pre-shared-devices-keys-import-job-status/) - [Restart a failed plugin by installation ID](/api/1nce-os/restart-a-failed-plugin-by-installation-id/) - [Restart AWS Integration](/api/1nce-os/restart-aws-integration/) - [Restart Webhook Integration](/api/1nce-os/restart-webhook-integration/) - [Test AWS Integration](/api/1nce-os/test-aws-integration/) - [Test template](/api/1nce-os/test-template/) - [Test Webhook Integration](/api/1nce-os/test-webhook-integration/) - [Uninstall a specific plugin by ID](/api/1nce-os/uninstall-a-specific-plugin-by-id/) - [Update Optimizer Template](/api/1nce-os/update-optimizer-template/) --- # Accept 1NCE OS Agreements Source: https://help.1nce.com/api/1nce-os/accept-1-nce-os-agreements/ `POST /v1/agreements/1nceos` Post request to accept the 1NCE OS Terms of Use and Data Processing agreements. Please note that with this request the agreements can only be accepted. ```json { "accepted": true } ``` - `201` — Created - `400` — Bad Request - `500` — Internal Server Error --- # Cancel all device action requests Source: https://help.1nce.com/api/1nce-os/cancel-all-device-action-requests/ `DELETE /v1/integrate/devices/{deviceId}/actions/requests` Cancel all device action requests. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Cancel single device action request Source: https://help.1nce.com/api/1nce-os/cancel-single-device-action-request/ `DELETE /v1/integrate/devices/actions/requests/{requestId}` Cancel single device action request. | Name | In | Required | Description | | --- | --- | --- | --- | | requestId | path | true | ID of device action request | - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Create Action Request for the LwM2M Device Source: https://help.1nce.com/api/1nce-os/create-action-request-for-the-lw-m-2-m-device/ `POST /v1/integrate/devices/{deviceId}/actions/LWM2M` Initiate LwM2M action like read, write, execute on specific device. It has to be connected to 1NCE LwM2M endpoint to invoke this event. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "action": "read", "resourceAddress": "/3/45/22", "data": "enable_sensor", "requestMode": "SEND_NOW", "sendAttempts": 1 } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Create Action Request On Specific CoAP Device. Source: https://help.1nce.com/api/1nce-os/create-action-request-on-specific-co-ap-device/ `POST /v1/integrate/devices/{deviceId}/actions/COAP` Initiate CoAP action on specific device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "path": "example?param1=query_param_example", "requestType": "GET", "requestMode": "SEND_NOW", "sendAttempts": 1 } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Create Action Request On Specific LwM2M Device Source: https://help.1nce.com/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/ `POST /v1/devices/{deviceId}/actions` Initiate LwM2M action like read, write, execute on specific device. It has to be connected to 1NCE LwM2M endpoint to invoke this event. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "action": "read", "resourceAddress": "/3/45/22", "data": "enable_sensor", "requestMode": "SEND_NOW", "sendAttempts": 1 } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Create Action Request On Specific UDP Device. Source: https://help.1nce.com/api/1nce-os/create-action-request-on-specific-udp-device/ `POST /v1/integrate/devices/{deviceId}/actions/UDP` Initiate UDP action on specific device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Create Action Requests for CoAP Devices. Source: https://help.1nce.com/api/1nce-os/create-action-requests-for-co-ap-devices/ `POST /v1/integrate/devices/actions/COAP` Initiate CoAP action on the devices. ```json { "deviceIds": [ "" ], "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "path": "example?param1=query_param_example", "requestType": "GET", "requestMode": "SEND_NOW", "sendAttempts": 1 } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Create Action Requests for LwM2M Devices. Source: https://help.1nce.com/api/1nce-os/create-action-requests-for-lw-m-2-m-devices/ `POST /v1/integrate/devices/actions/LWM2M` Initiate LwM2M actions like read, write, execute on the specified devices. The devices have to be connected to 1NCE LwM2M endpoint to invoke this event. ```json { "deviceIds": [ "" ], "action": "read", "resourceAddress": "/3/45/22", "data": "enable_sensor", "requestMode": "SEND_NOW", "sendAttempts": 1 } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Create Action Requests for UDP Devices. Source: https://help.1nce.com/api/1nce-os/create-action-requests-for-udp-devices/ `POST /v1/integrate/devices/actions/UDP` Initiate UDP action on devices. ```json { "deviceIds": [ "" ], "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" } ``` - `202` — Message describing the result of operation - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Create AWS Integration Source: https://help.1nce.com/api/1nce-os/create-aws-integration/ `POST /v1/integrate/clouds/aws` Creates AWS Integration, which becomes active only after customer Cloudformation stack is rolled out. ```json { "name": "", "eventTypes": [ { "type": "TELEMETRY_DATA", "version": "1.0.0" } ], "jsonPayloadEnabled": true } ``` - `201` — Created AWS Integration Details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Create geofence Source: https://help.1nce.com/api/1nce-os/create-geofence/ `POST /v1/locate/geofences` Create a new geofence. ```json { "name": "string", "eventTypes": [ "ENTER" ], "eventSources": [ "CellTower" ], "type": "string", "coordinates": [ 0 ] } ``` - `201` — Created - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Create Optimizer Template Source: https://help.1nce.com/api/1nce-os/create-optimizer-template/ `POST /v1/optimize/templates` Create a new Translation Service Template. ```json { "name": "", "template": "", "protocolFilter": "COAP", "status": "ACTIVE" } ``` - `201` — Created - `403` — Forbidden - `409` — Conflict - `422` — Unprocessable Entity - `500` — Internal Server Error --- # Create Pre-Shared Device Key Source: https://help.1nce.com/api/1nce-os/create-pre-shared-device-key/ `POST /v1/integrate/devices/{deviceId}/presharedkey` Post a new Custom Pre-Shared Key for a specific Device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "secretKey": "", "protocol": "COAP", "format": "STRING" } ``` - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Create Pre-shared Key for the Device Source: https://help.1nce.com/api/1nce-os/create-pre-shared-key-for-the-device/ `POST /v1/integrate/devices/{deviceId}/psk` Post a new Custom Pre-Shared Key for a specific Device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | ```json { "secretKey": "", "protocol": "COAP", "format": "STRING" } ``` - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Create Webhook Integration Source: https://help.1nce.com/api/1nce-os/create-webhook-integration/ `POST /v1/integrate/clouds/webhooks` Creates Webhook Integration. ```json { "name": "", "url": "https://www.example.com", "headers": {}, "eventTypes": [ { "type": "TELEMETRY_DATA", "version": "1.0.0" } ], "jsonPayloadEnabled": true } ``` - `201` — Created Webhook Integration Details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Delete geofence Source: https://help.1nce.com/api/1nce-os/delete-geofence/ `DELETE /v1/locate/geofences/{geofenceId}` Delete a geofence. | Name | In | Required | Description | | --- | --- | --- | --- | | geofenceId | path | true | unique geofence ID | - `204` — Deleted - `404` — Not Found Error - `500` — Internal Server Error --- # Delete Integration Source: https://help.1nce.com/api/1nce-os/delete-integration/ `DELETE /v1/integrate/clouds/{integrationId}` Delete Integration for a specific customer. | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `204` — No Content - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Delete Optimizer Template Source: https://help.1nce.com/api/1nce-os/delete-optimizer-template/ `DELETE /v1/optimize/templates/{templateId}` Delete a specific Optimizer Template. | Name | In | Required | Description | | --- | --- | --- | --- | | templateId | path | true | Unique Id of the Optimizer Template which should be deleted. | - `204` — No Content - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Disable ADL device location settings Source: https://help.1nce.com/api/1nce-os/disable-adl-device-location-settings/ `DELETE /v1/locate/devices/settings` Disables location-based settings (ADL) for a set of devices. ```json { "deviceIds": [ "string" ] } ``` - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `429` — Too Many Requests - `500` — Internal Server Error --- # Enable ADL device location settings Source: https://help.1nce.com/api/1nce-os/enable-adl-device-location-settings/ `POST /v1/locate/devices/settings` Enables location-based settings (ADL) for a set of devices. ```json { "deviceIds": [ "string" ], "details": { "frequency": 0 } } ``` - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `429` — Too Many Requests - `500` — Internal Server Error --- # Get a geofence Source: https://help.1nce.com/api/1nce-os/get-a-geofence/ `GET /v1/locate/geofences/{geofenceId}` Get details of a geofence. | Name | In | Required | Description | | --- | --- | --- | --- | | geofenceId | path | true | unique geofence ID | - `200` — OK - `404` — Not Found Error - `500` — Internal Server Error --- # Get a list of plugin installations Source: https://help.1nce.com/api/1nce-os/get-a-list-of-plugin-installations/ `GET /v1/partners/plugins` Retrieve a list of all installed plugins. - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get active device action requests Source: https://help.1nce.com/api/1nce-os/get-active-device-action-requests/ `GET /v1/integrate/devices/actions/requests/active` Get a list of active device action requests in the last 7 days. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | status | query | false | | | sort | query | false | | - `200` — OK - `400` — Bad Request - `403` — Forbidden - `500` — Internal Server Error --- # Get Administration Log Payload Source: https://help.1nce.com/api/1nce-os/get-administration-log-payload/ `GET /v1/administrationLogs/{adminLogId}/payload` Get a URL pointing to a single administration log payload. The received URL will trigger a download. | Name | In | Required | Description | | --- | --- | --- | --- | | adminLogId | path | true | Unique Id of the administration log for which the payload should be queried. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Administration Logs Statistics Source: https://help.1nce.com/api/1nce-os/get-administration-logs-statistics/ `GET /v1/administrationLogs/stats` Get the administration logs statistics for the current organization. | Name | In | Required | Description | | --- | --- | --- | --- | | timezone | query | true | Specify the needed timezone as string parameter (e.g., Europe/Amsterdam) for the resulting query output. | | category | query | false | Specify the category as string parameter for the resulting query output. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Administration Logs Source: https://help.1nce.com/api/1nce-os/get-administration-logs/ `GET /v1/administrationLogs` Get a list of the administration logs regarding the organization. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | | q | query | false | Filter parameter in {filter}:{value} format. Expects comma separated list of filtering criteria out of the following fields:
  • geofenceId
  • category
  • iccid
  • type
  • startDateTime (UTC)
  • endDateTime (UTC)

Example: "type:device,iccid:ICCID,startDateTime:2022-11-14T16:04:38.000Z"

| - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get All Customer Integrations Source: https://help.1nce.com/api/1nce-os/get-all-customer-integrations/ `GET /v1/integrate/clouds` Get All Customer Integrations details - `200` — All Customer Integration Details. - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get All Devices Source: https://help.1nce.com/api/1nce-os/get-all-devices/ `GET /v1/inspect/devices` Get a list of all the Customer SIMs/Devices for the current organisation in the 1NCE OS. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number of the requested devices page. Use this parameter to iterate through all devices on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | | sort | query | false | Sort values based on keys that are listed as a comma seperated list, prepend "-" for descending order. | | q | query | false | Filter parameter in {filter}:{value} format. Comma separated list of filtering criteria out of the following fields:
  • iccid

Example: "iccid:8988280666000000000"

| - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get all geofences Source: https://help.1nce.com/api/1nce-os/get-all-geofences/ `GET /v1/locate/geofences` Get an overview of all geofences. Rate limits apply for this endpoint. See [Rate Limit Policy](https://help.1nce.com/api/api-rate-limits/). | Name | In | Required | Description | | --- | --- | --- | --- | | pageSize | query | false | Parameter for specifying the queried items per page. | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | name | query | false | Name or Prefix of Geofence | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | scope | query | false | scope of geofences | - `200` — OK - `400` — Bad Request - `429` — Too Many Requests - `500` — Internal Server Error --- # Get archived device action requests Source: https://help.1nce.com/api/1nce-os/get-archived-device-action-requests/ `GET /v1/integrate/devices/actions/requests/archived` Get a list of archived device action requests in the last 7 days. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | status | query | false | | | sort | query | false | | - `200` — OK - `400` — Bad Request - `403` — Forbidden - `500` — Internal Server Error --- # Get CloudFormation Parameters Source: https://help.1nce.com/api/1nce-os/get-cloud-formation-parameters/ `GET /v1/integrate/clouds/aws/parameters` Get the URLs to download/rollout the customer CloudFormation stack templates. - `200` — OK - `401` — Unauthorized - `500` — Internal Server Error --- # Get Customer Integration Source: https://help.1nce.com/api/1nce-os/get-customer-integration/ `GET /v1/integrate/clouds/{integrationId}` Get Customer Integration details | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `200` — Customer Integration Details. - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Get customer settings Source: https://help.1nce.com/api/1nce-os/get-customer-settings/ `GET /v1/settings/1nceos` Gets customer settings related to 1NCE OS. | Name | In | Required | Description | | --- | --- | --- | --- | | pageSize | query | false | Parameter for specifying the queried items per page. | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | language | query | false | Identifies in what language the description should be returned. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get details about a specific plugin installation Source: https://help.1nce.com/api/1nce-os/get-details-about-a-specific-plugin-installation/ `GET /v1/partners/plugins/{pluginId}` Retrieve details about a specific 1NCE OS plugin by it's installation ID. | Name | In | Required | Description | | --- | --- | --- | --- | | pluginId | path | true | Unique identifier of the plugin installation. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Get device action requests Source: https://help.1nce.com/api/1nce-os/get-device-action-requests/ `GET /v1/integrate/devices/actions/requests` Get a list of device action requests in the last 7 days. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | status | query | false | | | sort | query | false | | - `200` — OK - `400` — Bad Request - `403` — Forbidden - `500` — Internal Server Error --- # Get Device Celltower location resolutions Source: https://help.1nce.com/api/1nce-os/get-device-celltower-location-resolutions/ `GET /v1/locate/devices/{deviceId}/activity` Get Cell location resolutions for one device (maximum of last 7 days). ![Creative Commons License](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | startDateTime | query | false | Timestamp from where onwards the historic data should be queried. If not provided while "endDateTime" is provided defaults to 1 day before "endDateTime" timestamp, otherwise defaults to 1 day from now | | endDateTime | query | false | Timestamp up to where the historic data should be queried. If not provided while "startDateTime" is provided defaults to 1 day after "startDateTime" timestamp, otherwise defaults to now | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get device endpoints Source: https://help.1nce.com/api/1nce-os/get-device-endpoints/ `GET /v1/integrate/devices/endpoints` Get details about the device endpoints. - `200` — OK - `403` — Forbidden - `500` — Internal Server Error --- # Get Device Historian Insights Source: https://help.1nce.com/api/1nce-os/get-device-historian-insights/ `GET /v1/inspect/devices/{deviceId}/history/insights` Get insights of a unique SIM device for the Historian. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | startDateTime | query | false | Timestamp from where onwards the historic data messages should be queried. | | endDateTime | query | false | Timestamp until when the historic data messages should be queried. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | interval | query | false | The interval for which grouping of statistics should occur. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Device Historian Messages Source: https://help.1nce.com/api/1nce-os/get-device-historian-messages/ `GET /v1/inspect/devices/{deviceId}/history` Get historic message data for a specific SIM device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | startDateTime | query | false | Timestamp from where onwards the historic data messages should be queried. | | endDateTime | query | false | Timestamp until when the historic data messages should be queried. | | pageSize | query | false | Parameter for specifying the queried items per page. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | nextToken | query | false | This API query uses token-based pagination. Each queried page will include a nextToken for accessing the next page for pagination. Please use the returned token in the nextToken query parameters to obtain the next page. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Device Positions Source: https://help.1nce.com/api/1nce-os/get-device-positions/ `GET /v1/locate/devices/{deviceId}/positions` Get positions of a specific device (maximum of last 7 days). ![Creative Commons License](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | sort | query | false | Comma seperated list of device property keys in order. Prefix key with `-` to sort descending. | | source | query | false | Source of the position. | | startDateTime | query | false | | | endDateTime | query | false | | | pageSize | query | false | Parameter for specifying the queried items per page. | | mode | query | false | Use ALL for a paginated list of all positions and SUMMARY to get the first, last and some positions inbetween. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Device Telemetry Source: https://help.1nce.com/api/1nce-os/get-device-telemetry/ `GET /v1/inspect/devices/{deviceId}/telemetry` Get the current/last repored Shadow State (telemetry) Data for a specific Device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | protocol | query | false | Filter out shadow state data for specific protocol:
  • LWM2M
  • UDP
  • COAP
| - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Devices Statistics Source: https://help.1nce.com/api/1nce-os/get-devices-statistics/ `GET /v1/devices/stats` Get general statistics related to customer devices - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Historian Insights Source: https://help.1nce.com/api/1nce-os/get-historian-insights/ `GET /v1/inspect/devices/history/insights` Get insights for all devices from the Historian based on the optional filters. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | iccid | query | false | ICCID of a SIM device, used to identifiy each 1NCE SIM. | | startDateTime | query | false | Timestamp from where onwards the historic data messages should be queried. | | endDateTime | query | false | Timestamp until when the historic data messages should be queried. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | interval | query | false | The interval for which grouping of statistics should occur. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Historian Messages Source: https://help.1nce.com/api/1nce-os/get-historian-messages/ `GET /v1/inspect/devices/history` Get a list of historic messages for devices based on the optional filter parameters. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | iccid | query | false | ICCID of a SIM device, used to identifiy each 1NCE SIM. | | startDateTime | query | false | Timestamp from where onwards the historic data messages should be queried. | | endDateTime | query | false | Timestamp until when the historic data messages should be queried. | | pageSize | query | false | Parameter for specifying the queried items per page. | | protocol | query | false | Filter out data for specific protocols:
  • LWM2M
  • UDP
  • COAP
| | nextToken | query | false | This API query uses token-based pagination. Each queried page will include a nextToken for accessing the next page for pagination. Please use the returned token in the nextToken query parameters to obtain the next page. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Integration Event Types Source: https://help.1nce.com/api/1nce-os/get-integration-event-types/ `GET /v1/integrate/clouds/eventTypes` Get Available Integration Event Types. - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Latest Devices Positions Source: https://help.1nce.com/api/1nce-os/get-latest-devices-positions/ `GET /v1/locate/positions/latest` Get latest positions of customer devices (maximum of last 7 days). Only one latest position is possible for a single device independent of source: either Celltower or GPS. This means that `source` query parameter selection can lead to no latest position returned for some devices. ![Creative Commons License](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | query | false | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | sort | query | false | Comma seperated list of device property keys in order. Prefix key with `-` to sort descending. | | source | query | false | Source of the position. | | startDateTime | query | false | | | endDateTime | query | false | | | longitudeFrom | query | false | | | longitudeTo | query | false | | | latitudeFrom | query | false | | | latitudeTo | query | false | | | pageSize | query | false | Parameter for specifying the queried items per page. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get Optimizer Templates Source: https://help.1nce.com/api/1nce-os/get-optimizer-templates/ `GET /v1/optimize/templates` Get all Translation Service Templates for the current organization. - `200` — OK - `403` — Forbidden - `500` — Internal Server Error --- # Get per-device settings Source: https://help.1nce.com/api/1nce-os/get-per-device-settings/ `GET /v1/inspect/devices/settings/{device_setting_name}` Retrieves the list of per-device settings for a given device setting name, with optional ICCID and pagination filters. | Name | In | Required | Description | | --- | --- | --- | --- | | device_setting_name | path | true | Name of the device setting to retrieve. | | iccid | query | false | ICCID of a SIM device, used to identifiy each 1NCE SIM. | | page | query | false | Number of the requested page. Use this parameter to iterate through all items on the different pages. The total amount of pages is listed in the response body (pageAmount). | | pageSize | query | false | Parameter for specifying the queried items per page. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `429` — Too Many Requests - `500` — Internal Server Error --- # Get Pre-Shared Device Key Source: https://help.1nce.com/api/1nce-os/get-pre-shared-device-key/ `GET /v1/integrate/devices/{deviceId}/psk/{protocol}` Get the Pre-Shared Key of a specific Device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | | protocol | path | true | Available protocols:
  • LWM2M
  • UDP
  • COAP
| - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Get Pre-Shared Keys Import Job Status Source: https://help.1nce.com/api/1nce-os/get-pre-shared-keys-import-job-status/ `GET /v1/integrate/devices/presharedkey/jobs` Get status of Pre-Shared Keys Import jobs for the last 30 days. - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get savings Source: https://help.1nce.com/api/1nce-os/get-savings/ `GET /v1/optimize/savings` Get statistics about the savings by using the optimizer. | Name | In | Required | Description | | --- | --- | --- | --- | | range | query | false | Specify the range in days to receive data about. | | protocol | query | false | Filter out by specific protocols:
  • UDP
  • COAP
| | iccid | query | false | ICCID of a SIM device, used to identifiy each 1NCE SIM. | - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Get single device action request Source: https://help.1nce.com/api/1nce-os/get-single-device-action-request/ `GET /v1/integrate/devices/actions/requests/{requestId}` Get details about the device action request. | Name | In | Required | Description | | --- | --- | --- | --- | | requestId | path | true | ID of device action request | - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Get single device endpoint Source: https://help.1nce.com/api/1nce-os/get-single-device-endpoint/ `GET /v1/integrate/devices/endpoints/{protocol}` Get details about the device endpoint of a specific protocol. | Name | In | Required | Description | | --- | --- | --- | --- | | protocol | path | true | Available protocols:
  • LWM2M
  • UDP
  • COAP
| - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Get Single Device Source: https://help.1nce.com/api/1nce-os/get-single-device/ `GET /v1/inspect/devices/{deviceId}` Get detailed metadata from one specific Device. | Name | In | Required | Description | | --- | --- | --- | --- | | deviceId | path | true | The unique device ID which identifies each 1NCE SIM. Can be obtained from the Get All Devices API query. For 1NCE SIMS the device ID is equal to its iccid. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Import Pre-Shared Keys for Devices Source: https://help.1nce.com/api/1nce-os/import-pre-shared-keys-for-devices/ `POST /v1/integrate/devices/presharedkey/jobs` Import new Custom Pre-Shared Keys for multiple Devices. ```json [ { "deviceId": "", "secretKey": "", "protocol": "COAP", "format": "STRING" } ] ``` - `202` — Accepted - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Import Pre-Shared Keys for the Devices Source: https://help.1nce.com/api/1nce-os/import-pre-shared-keys-for-the-devices/ `POST /v1/integrate/devices/psk/jobs` Import new Custom Pre-Shared Keys for multiple Devices. ```json [ { "deviceId": "", "secretKey": "", "protocol": "COAP", "format": "STRING" } ] ``` - `202` — Accepted - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Install Datacake plugin for 1NCE OS Source: https://help.1nce.com/api/1nce-os/install-datacake-plugin-for-1-nce-os/ `POST /v1/partners/DATACAKE/plugins` Allows setting up an integration with Datacake workspace to allow data transfer from 1NCE OS. ```json { "workspaceId": "abcdef12-0000-0000-ab12-123456789012" } ``` - `201` — Successful Datacake plugin installation response details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Install Memfault plugin for 1NCE OS Source: https://help.1nce.com/api/1nce-os/install-memfault-plugin-for-1-nce-os/ `POST /v1/partners/MEMFAULT/plugins` Allows setting up an integration with Memfault to allow seamless device debugging via 1NCE OS CoAP proxy. ```json {} ``` - `201` — Successful Memfault plugin installation response details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Install Mender plugin for 1NCE OS Source: https://help.1nce.com/api/1nce-os/install-mender-plugin-for-1-nce-os/ `POST /v1/partners/MENDER/plugins` Allows setting up an integration with Mender to allow seamless firmware update management via 1NCE OS CoAP proxy. Public and private keys are optional fields, but if they are used, both must be provided ```json { "tenantToken": "string", "privateKey": "string", "publicKey": "string" } ``` - `201` — Successful Mender plugin installation response details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Install Tartabit plugin for 1NCE OS Source: https://help.1nce.com/api/1nce-os/install-tartabit-plugin-for-1-nce-os/ `POST /v1/partners/TARTABIT/plugins` Allows setting up an integration with Tartabit to integrate with Azure, Oracle Cloud Infrastructure, Google Cloud and other cloud services via 1NCE OS. ```json { "serverDomain": "string", "webhookKey": "string" } ``` - `201` — Successful Tartabit plugin installation response details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `409` — Conflict - `500` — Internal Server Error --- # Patch a geofence Source: https://help.1nce.com/api/1nce-os/patch-a-geofence/ `PATCH /v1/locate/geofences/{geofenceId}` Update an existing geofence | Name | In | Required | Description | | --- | --- | --- | --- | | geofenceId | path | true | unique geofence ID | ```json { "name": "string", "eventTypes": [ "ENTER" ], "eventSources": [ "CellTower" ] } ``` - `200` — OK - `400` — Bad Request - `404` — Not Found Error - `500` — Internal Server Error --- # Patch Customer Integration Source: https://help.1nce.com/api/1nce-os/patch-customer-integration/ `PATCH /v1/integrate/clouds/{integrationId}` Patch Customer Integration | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | ```json { "url": "https://www.example.com", "headers": {}, "eventTypes": [ { "type": "TELEMETRY_DATA", "version": "1.0.0" } ], "jsonPayloadEnabled": true } ``` - `200` — Customer Integration Details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Patch Customer Webhook Integration Source: https://help.1nce.com/api/1nce-os/patch-customer-webhook-integration/ `PATCH /v1/integrate/clouds/webhooks/{integrationId}` Patch Customer Webhook Integration | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | ```json { "url": "https://www.example.com", "headers": {}, "eventTypes": [ { "type": "TELEMETRY_DATA", "version": "1.0.0" } ], "jsonPayloadEnabled": true } ``` - `200` — Customer Webhook Integration Details. - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Patch Setting Details Source: https://help.1nce.com/api/1nce-os/patch-setting-details/ `PATCH /v1/settings/1nceos/{name}/details` Patches the operating mode (`details.mode`) of a 1NCE OS setting. Currently only the `ADVANCED_CELL_TOWER_LOCATION` setting is supported, and only `CUSTOM` is accepted as a value. | Name | In | Required | Description | | --- | --- | --- | --- | | name | path | true | Name of the setting whose details to patch. | ```json { "mode": "CUSTOM" } ``` - `200` — An object describing the updated setting. - `400` — Bad Request - `403` — Forbidden - `404` — Not Found Error - `429` — Too Many Requests - `500` — Internal Server Error --- # Patch Settings Source: https://help.1nce.com/api/1nce-os/patch-settings/ `PATCH /v1/settings/1nceos/{name}` Enables or disables different settings for the 1NCE OS integration of a customer. Disclaimer: I acknowledge that activating the location feature involves processing nearby Cell Tower data by 1NCE. 1NCE processing of data is done anonymously. I understand that if the use of the service by me makes it linkable to individuals, additional data related responsibilities may apply. As per 1NCE General Terms and Conditions (GTC), I am solely responsible for complying with Data Protection laws and regulations and obtaining necessary consents. | Name | In | Required | Description | | --- | --- | --- | --- | | name | path | true | Key name parameter of the setting to update. | ```json { "state": "ENABLED", "readAndAcceptedDisclaimer": true } ``` - `200` — An object describing a setting - `400` — Bad Request - `403` — Forbidden - `500` — Internal Server Error --- # Patch single device endpoint Source: https://help.1nce.com/api/1nce-os/patch-single-device-endpoint/ `PATCH /v1/integrate/devices/endpoints/{protocol}` Update endpoint related settings. | Name | In | Required | Description | | --- | --- | --- | --- | | protocol | path | true | Available protocols:
  • LWM2M
  • UDP
  • COAP
| ```json { "settings": [ { "name": "LWM2M_PASSIVE_REPORTING", "state": "ENABLED" } ] } ``` - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Pre-Shared Devices Keys Import Job Status Source: https://help.1nce.com/api/1nce-os/pre-shared-devices-keys-import-job-status/ `GET /v1/integrate/devices/psk/jobs` Get status of Pre-Shared Keys Import jobs for the last 30 days. - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Restart a failed plugin by installation ID Source: https://help.1nce.com/api/1nce-os/restart-a-failed-plugin-by-installation-id/ `POST /v1/partners/plugins/{pluginId}/restart` Attempt to restart a plugin that is in a failed state. | Name | In | Required | Description | | --- | --- | --- | --- | | pluginId | path | true | Unique identifier of the plugin installation. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Restart AWS Integration Source: https://help.1nce.com/api/1nce-os/restart-aws-integration/ `POST /v1/integrate/clouds/aws/{integrationId}/restart` Restart AWS integration by forwarding test message to the integration. | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Restart Webhook Integration Source: https://help.1nce.com/api/1nce-os/restart-webhook-integration/ `POST /v1/integrate/clouds/webhooks/{integrationId}/restart` Restart Webhook integration by forwarding test message to the integration. | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Test AWS Integration Source: https://help.1nce.com/api/1nce-os/test-aws-integration/ `POST /v1/integrate/clouds/aws/{integrationId}/test` Test AWS integration by forwarding test message to the integration. | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Test template Source: https://help.1nce.com/api/1nce-os/test-template/ `POST /v1/optimize/messages/test` Test a template with a sample input message. ```json { "template": "", "payload": "" } ``` - `200` — OK - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `500` — Internal Server Error --- # Test Webhook Integration Source: https://help.1nce.com/api/1nce-os/test-webhook-integration/ `POST /v1/integrate/clouds/webhooks/{integrationId}/test` Test Webhook integration by forwarding test message to the integration. | Name | In | Required | Description | | --- | --- | --- | --- | | integrationId | path | true | unique integration ID | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `500` — Internal Server Error --- # Uninstall a specific plugin by ID Source: https://help.1nce.com/api/1nce-os/uninstall-a-specific-plugin-by-id/ `DELETE /v1/partners/plugins/{pluginId}` Uninstall a specific plugin by ID to remove the functionality provided by the plugin. | Name | In | Required | Description | | --- | --- | --- | --- | | pluginId | path | true | Unique identifier of the plugin installation. | - `204` — NoContent - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found Error - `500` — Internal Server Error --- # Update Optimizer Template Source: https://help.1nce.com/api/1nce-os/update-optimizer-template/ `PATCH /v1/optimize/templates/{templateId}` Update a specific Optimizer Template. | Name | In | Required | Description | | --- | --- | --- | --- | | templateId | path | true | Unique Id of the Optimizer Template for which the update should be applied. | ```json { "name": "", "template": "", "protocolFilter": "COAP", "status": "ACTIVE" } ``` - `200` — OK - `403` — Forbidden - `404` — Not Found Error - `409` — Conflict - `422` — Unprocessable Entity - `500` — Internal Server Error --- # API Best Practices Source: https://help.1nce.com/api/api-best-practices/ # API Best Practices The 1NCE Management API provides developers with a robust toolset to manage SIM cards, usage data, and connectivity. By following the practices outlined below, you can ensure a reliable and efficient integration with the API while minimizing errors and maximizing performance. This guide will focus on key areas such as error handling, pagination, rate limits, and best practices for API calls. It references the latest version of the 1NCE OpenAPI specification and additional insights into rate limits and large SIM batch monitoring. ## 1. Authentication and Authorization To access the 1NCE API, developers must use a Bearer token obtained via the `/oauth/token` endpoint using the client credentials grant type. Ensure that this token is securely stored and refreshed as needed before expiry. **Example Authentication Request:** ```http POST /oauth/token HTTP/1.1 Content-Type: application/json { "grant_type": "client_credentials" } ``` **Example Authorization Header:** ```http Authorization: Bearer YOUR_ACCESS_TOKEN ``` ### Best Practices: * **Rotate Tokens Securely:** Store tokens securely in environment variables or a dedicated secret management system. * **Handle Expired Tokens:** Use the `expires_in` field from the token response to know when a token will expire. Proactively refresh the token before it expires. ## 2. HTTP Status Codes and Error Handling When making API requests, it's important to handle HTTP status codes properly to manage errors and retry appropriately. **Common Status Codes:** * **200 OK:** The request was successful. * **201 Created:** The resource was successfully created. * **400 Bad Request:** The request is malformed (e.g., missing required fields). * **401 Unauthorized:** Authentication failed; ensure your token is valid. * **403 Forbidden:** You lack the necessary permissions. * **404 Not Found:** The requested resource does not exist. * **429 Too Many Requests**: Rate limit exceeded (see Rate Limiting below). * **500 Internal Server Error:** Retry using exponential backoff if this is a transient issue. **Example Error Handling Logic:** ```python response = requests.get(api_url, headers=headers) if response.status_code == 200: # Success elif response.status_code == 400: print("Bad Request - Check your input parameters.") elif response.status_code == 401: print("Authentication failed.") elif response.status_code == 429: print("Rate limit exceeded. Wait before retrying.") else: print(f"Error: {response.status_code}") ``` ## 3. API Rate Limits ### Know the Limits of the API The 1NCE API has rate limits to prevent misuse and overloading. These limits ensure that the API can efficiently handle queries and configurations of 1NCE SIMs and services without impacting the system's performance for all customers. Review the current rate limits for all 1NCE Management API endpoints on the [API Rate Limits](/api/api-rate-limits) page. The rate limits have been designed based on analysis of typical usage patterns and should not interfere with common use cases for monitoring or managing 1NCE services. ### Handling Rate Limit Errors * **Monitor the** `Retry-After` **header** in 429 responses, which indicates how long to wait before retrying. * **Use exponential backoff** for retries: Start with a small delay and increase it with each subsequent retry. Example Retry Strategy: ```python import time def api_call_with_retry(url, headers): for attempt in range(5): response = requests.get(url, headers=headers) if response.status_code == 429: retry_after = int(response.headers.get("Retry-After", 1)) time.sleep(retry_after) else: return response raise Exception("Max retries reached.") ``` ## 4. Pagination When fetching large datasets like lists of SIMs, the API paginates results. You can control pagination using the page and pageSize query parameters. ### Key Pagination Parameters: * **page:** The page number to retrieve (default: 1). * **pageSize:** Number of items per page (maximum: 100). The response includes headers such as `X-Total-Count` (total items) and `X-Total-Pages` (total pages) to help navigate through the pages. **Example Pagination Request:** ```http GET /v1/sims?page=1&pageSize=100 HTTP/1.1 ``` **Example Pagination Loop:** ```python def fetch_paginated_sims(api_url, headers): page = 1 results = [] while True: response = requests.get(f"{api_url}?page={page}&pageSize=100", headers=headers) data = response.json() results.extend(data['results']) if page >= int(response.headers['X-Total-Pages']): break page += 1 return results ``` ## 5. Bulk Operations vs. Single Operations For efficiency, use bulk API endpoints when making changes to multiple SIMs at once, such as activating or deactivating several SIMs. Bulk requests minimize the number of API calls and reduce server load. **Example Bulk SIM Update:** ```http POST /v1/sims HTTP/1.1 Content-Type: application/json [ { "iccid": "8988280666000000000", "status": "Enabled" }, { "iccid": "8988280666000000001", "status": "Disabled" } ] ``` ### Best Practices: * **Use bulk calls for operations affecting multiple resources:** Instead of updating each SIM individually, use bulk calls to send a list of ICCIDs in one request. * **Asynchronous processing:** Some operations are queued and processed asynchronously. Monitor the status of bulk operations to ensure all items are processed. Monitoring can be done using the [Data Streamer](/docs/platform-services/platform-services-data-streamer/data-streamer-event-records) service with dedicated events acknowledging each operation. ## 6. Efficient Data Usage and Large SIM Batch Monitoring When working with a large number of SIMs, it is important to manage API usage efficiently to avoid overloading the system and to ensure that your client runs smoothly. ### Large SIM Batch Monitoring It's still advisable to avoid frequent, high-volume API calls. 1NCE recommends using the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer) for monitoring large batches of SIMs. The Data Streamer offers near real-time monitoring of SIM events and usage without requiring constant API queries. Using the Data Streamer service minimizes the need to query the API frequently, helping to offload the system and ensuring better performance, especially when dealing with large-scale monitoring tasks. **Best Practices:** * **Limit API Polling:** Avoid polling the API frequently for updates. Use webhooks or streaming services when available. * **Use the Data Streamer:** For monitoring large SIM batches, leverage the Data Streamer Service to avoid unnecessary API load and receive near real-time updates. ## 7. Timeout and Connection Management To ensure smooth operation of your API client: * **Set timeouts:** Avoid hanging requests by setting a reasonable timeout for your API calls. * **Manage connection pooling:** For high-volume applications, use connection pooling to optimize resource usage. **Example with Timeout:** ```python response = requests.get(api_url, headers=headers, timeout=5) ``` ## Summary Integrating with the 1NCE Management API efficiently requires adhering to best practices for error handling, rate limiting, and making optimized API calls. By following these guidelines, you can ensure that your API client is performant, resilient to errors, and scalable for handling large datasets or high-frequency requests. Ensure your development workflow incorporates proper error handling, token management, bulk operations, and efficient API usage to maximize the value of the 1NCE platform. For large-scale monitoring, the Data Streamer Service provides an ideal solution to manage SIM batches in real time without unnecessary API load. --- # API Rate Limits Source: https://help.1nce.com/api/api-rate-limits/ # API Rate Limits The 1NCE API can be used by any customer to query and configure settings of 1NCE SIMs, products and related services. To protect the API from misusage and overloading, certain rate limits for the endpoints are set. The rate limits are derived from analyzing the existing application case patterns of 1NCE customers. Therefore, the API rate limits should not interfere with common use cases for monitoring or controlling 1NCE services. Listed below are the enforced rate limits for endpoints available through the 1NCE Management API. These limits are fixed and cannot be adjusted. | Endpoint | API Rate Limit | | --- | --- | | **Authorization:** `/oauth` | 600 requests per IP address per minute | | **SIM Management:** `/sims` | 10 requests per second per Customer | | **Order Management:** `/orders` | 100 requests per IP address per 5 minutes | | **Product Information:** `/products` | 100 requests per IP address per 5 minutes | | **Support Management:** `/support` | 100 requests per IP address per 5 minutes | Listed below are the default rate limits for 1NCE OS endpoints available through the 1NCE Management API. These limits may be adjusted upon request. | Methods | Endpoint | Default API Rate Limit | | --- | --- | --- | | GET | **Get all geofences:** `/locate/geofences`| 30 requests per minute per Customer | | POST | **Enable ADL device location settings:** `/locate/devices/settings` | 120 requests per minute per Customer | | DELETE | **Disable ADL device location settings:** `/locate/devices/settings` | 120 requests per minute per Customer | | GET | **Get per-device settings:** `/inspect/devices/settings/{device_setting_name}` | 120 requests per minute per Customer | | PATCH | **Patch Setting Details:** `/settings/1nceos/{name}/details` | 5 requests per minute per Customer | --- ## Large SIM Batch Monitoring Despite the SIM Management endpoints not having any rate limit set, it is advised to be gentle with the SIM Management API usage. 1NCE recommends to avoid very regular, high frequency API access with large number of requests for monitoring. The 1NCE API is a great tool for monitoring and querying data, but for regular monitoring of large SIM batches 1NCE recommends to use the Data Streamer Service. The streaming service allows to monitor SIM Events and Usages as it offers near real-time monitoring without the need to query the API regularly. If there are any issues or questions regarding the API integration, feel free to contact our [1NCE Support](https://1nce.com/en-eu/support/contact) for technical guidance. --- # Authorization Source: https://help.1nce.com/api/authorization/authorization/ Documentation of the authentication used for the 1NCE APIs. - [Obtain Access Token](/api/authorization/post-access-token-post/) --- # Obtain Access Token Source: https://help.1nce.com/api/authorization/post-access-token-post/ `POST /oauth/token` Obtain a token for accessing other 1NCE API resources by using a POST request with a valid username and password combination for a 1NCE user account that has the permission to use the API. ```json { "grant_type": "client_credentials" } ``` - `200` — OK - `400` — Bad Request - `404` — Not Found --- # Administration Logs Source: https://help.1nce.com/api/category/1nce-os/administration-logs/ - [Get Administration Logs](/api/1nce-os/get-administration-logs/) - [Get Administration Logs Statistics](/api/1nce-os/get-administration-logs-statistics/) - [Get Administration Log Payload](/api/1nce-os/get-administration-log-payload/) --- # Agreements Source: https://help.1nce.com/api/category/1nce-os/agreements/ - [Accept 1NCE OS Agreements](/api/1nce-os/accept-1-nce-os-agreements/) --- # Device Inspector Source: https://help.1nce.com/api/category/1nce-os/device-inspector/ - [Get All Devices](/api/1nce-os/get-all-devices/) - [Get Single Device](/api/1nce-os/get-single-device/) - [Get Device Telemetry](/api/1nce-os/get-device-telemetry/) - [Get Device Historian Messages](/api/1nce-os/get-device-historian-messages/) - [Get Historian Messages](/api/1nce-os/get-historian-messages/) - [Get Device Historian Insights](/api/1nce-os/get-device-historian-insights/) - [Get Historian Insights](/api/1nce-os/get-historian-insights/) - [Get per-device settings](/api/1nce-os/get-per-device-settings/) --- # Device Locator Source: https://help.1nce.com/api/category/1nce-os/device-locator/ - [Get Device Positions](/api/1nce-os/get-device-positions/) - [Get Latest Devices Positions](/api/1nce-os/get-latest-devices-positions/) - [Get Device Celltower location resolutions](/api/1nce-os/get-device-celltower-location-resolutions/) - [Disable ADL device location settings](/api/1nce-os/disable-adl-device-location-settings/) - [Enable ADL device location settings](/api/1nce-os/enable-adl-device-location-settings/) - [Get all geofences](/api/1nce-os/get-all-geofences/) - [Create geofence](/api/1nce-os/create-geofence/) - [Delete geofence](/api/1nce-os/delete-geofence/) - [Get a geofence](/api/1nce-os/get-a-geofence/) - [Patch a geofence](/api/1nce-os/patch-a-geofence/) --- # Devices Source: https://help.1nce.com/api/category/1nce-os/devices/ - [Create Action Request On Specific LwM2M Device](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/) - [Get Devices Statistics](/api/1nce-os/get-devices-statistics/) --- # IoT Integrator Source: https://help.1nce.com/api/category/1nce-os/io-t-integrator/ - [Get device endpoints](/api/1nce-os/get-device-endpoints/) - [Get single device endpoint](/api/1nce-os/get-single-device-endpoint/) - [Patch single device endpoint](/api/1nce-os/patch-single-device-endpoint/) - [Get device action requests](/api/1nce-os/get-device-action-requests/) - [Get active device action requests](/api/1nce-os/get-active-device-action-requests/) - [Get archived device action requests](/api/1nce-os/get-archived-device-action-requests/) - [Cancel all device action requests](/api/1nce-os/cancel-all-device-action-requests/) - [Cancel single device action request](/api/1nce-os/cancel-single-device-action-request/) - [Get single device action request](/api/1nce-os/get-single-device-action-request/) - [Create Pre-Shared Device Key](/api/1nce-os/create-pre-shared-device-key/) - [Get Pre-Shared Keys Import Job Status](/api/1nce-os/get-pre-shared-keys-import-job-status/) - [Import Pre-Shared Keys for Devices](/api/1nce-os/import-pre-shared-keys-for-devices/) - [Create Pre-shared Key for the Device](/api/1nce-os/create-pre-shared-key-for-the-device/) - [Get Pre-Shared Device Key](/api/1nce-os/get-pre-shared-device-key/) - [Pre-Shared Devices Keys Import Job Status](/api/1nce-os/pre-shared-devices-keys-import-job-status/) - [Import Pre-Shared Keys for the Devices](/api/1nce-os/import-pre-shared-keys-for-the-devices/) - [Create Action Request for the LwM2M Device](/api/1nce-os/create-action-request-for-the-lw-m-2-m-device/) - [Create Action Requests for LwM2M Devices.](/api/1nce-os/create-action-requests-for-lw-m-2-m-devices/) - [Create Action Request On Specific CoAP Device.](/api/1nce-os/create-action-request-on-specific-co-ap-device/) - [Create Action Requests for CoAP Devices.](/api/1nce-os/create-action-requests-for-co-ap-devices/) - [Create Action Request On Specific UDP Device.](/api/1nce-os/create-action-request-on-specific-udp-device/) - [Create Action Requests for UDP Devices.](/api/1nce-os/create-action-requests-for-udp-devices/) - [Get CloudFormation Parameters](/api/1nce-os/get-cloud-formation-parameters/) - [Restart AWS Integration](/api/1nce-os/restart-aws-integration/) - [Test AWS Integration](/api/1nce-os/test-aws-integration/) - [Create AWS Integration](/api/1nce-os/create-aws-integration/) - [Delete Integration](/api/1nce-os/delete-integration/) - [Get Customer Integration](/api/1nce-os/get-customer-integration/) - [Patch Customer Integration](/api/1nce-os/patch-customer-integration/) - [Get All Customer Integrations](/api/1nce-os/get-all-customer-integrations/) - [Get Integration Event Types](/api/1nce-os/get-integration-event-types/) - [Create Webhook Integration](/api/1nce-os/create-webhook-integration/) - [Patch Customer Webhook Integration](/api/1nce-os/patch-customer-webhook-integration/) - [Restart Webhook Integration](/api/1nce-os/restart-webhook-integration/) - [Test Webhook Integration](/api/1nce-os/test-webhook-integration/) --- # Optimizer Source: https://help.1nce.com/api/category/1nce-os/optimizer/ - [Test template](/api/1nce-os/test-template/) - [Get savings](/api/1nce-os/get-savings/) - [Get Optimizer Templates](/api/1nce-os/get-optimizer-templates/) - [Create Optimizer Template](/api/1nce-os/create-optimizer-template/) - [Delete Optimizer Template](/api/1nce-os/delete-optimizer-template/) - [Update Optimizer Template](/api/1nce-os/update-optimizer-template/) --- # Plugin system Source: https://help.1nce.com/api/category/1nce-os/plugin-system/ - [Install Datacake plugin for 1NCE OS](/api/1nce-os/install-datacake-plugin-for-1-nce-os/) - [Install Mender plugin for 1NCE OS](/api/1nce-os/install-mender-plugin-for-1-nce-os/) - [Install Tartabit plugin for 1NCE OS](/api/1nce-os/install-tartabit-plugin-for-1-nce-os/) - [Install Memfault plugin for 1NCE OS](/api/1nce-os/install-memfault-plugin-for-1-nce-os/) - [Uninstall a specific plugin by ID](/api/1nce-os/uninstall-a-specific-plugin-by-id/) - [Get details about a specific plugin installation](/api/1nce-os/get-details-about-a-specific-plugin-installation/) - [Restart a failed plugin by installation ID](/api/1nce-os/restart-a-failed-plugin-by-installation-id/) - [Get a list of plugin installations](/api/1nce-os/get-a-list-of-plugin-installations/) --- # Settings Source: https://help.1nce.com/api/category/1nce-os/settings/ - [Patch Settings](/api/1nce-os/patch-settings/) - [Patch Setting Details](/api/1nce-os/patch-setting-details/) - [Get customer settings](/api/1nce-os/get-customer-settings/) --- # Bearer Authorization Source: https://help.1nce.com/api/category/authorization/bearer-authorization/ - [Obtain Access Token](/api/authorization/post-access-token-post/) --- # Orders Source: https://help.1nce.com/api/category/order-management/orders/ - [Get All Orders](/api/order-management/get-orders-using-get/) - [Create Order](/api/order-management/post-order-using-post/) - [Get Single Order](/api/order-management/get-order-using-get/) --- # Products Source: https://help.1nce.com/api/category/product-information/products/ - [Get All Products](/api/product-information/get-products-using-get/) --- # Connectivity Source: https://help.1nce.com/api/category/sim-management/connectivity/ - [Get SIM Connectivity](/api/sim-management/get-connectivity-info-for-sim-using-get/) - [Create Connectivity Reset](/api/sim-management/reset-connectivity-using-post/) --- # General SIMs Source: https://help.1nce.com/api/category/sim-management/general-si-ms/ - [Get All SIMs](/api/sim-management/get-sims-using-get/) - [Create Multiple SIM Configuration](/api/sim-management/update-sims-using-post/) - [Get Single SIM](/api/sim-management/get-sim-using-get/) - [Create Single SIM Configuration](/api/sim-management/update-sim-using-put/) - [Get SIM Status](/api/sim-management/get-status-for-sim-using-get/) - [Create SIM Transfer](/api/sim-management/sim-transfer-using-post/) --- # SIM Events Source: https://help.1nce.com/api/category/sim-management/sim-events/ - [Get SIM Events](/api/sim-management/get-events-for-sim-using-get/) --- # SIM Extension Source: https://help.1nce.com/api/category/sim-management/sim-extension/ - [Create SIM Extension](/api/sim-management/extend-sims-using-post/) --- # SIM Usage Source: https://help.1nce.com/api/category/sim-management/sim-usage/ - [Get SIM Usage](/api/sim-management/get-usage-for-sim-using-get/) - [Get SIM Data Quota](/api/sim-management/get-data-quota-for-sim-using-get/) - [Get SIM SMS Quota](/api/sim-management/get-sms-quota-for-sim-using-get/) --- # SMS Source: https://help.1nce.com/api/category/sim-management/sms/ - [Get MT/MO-SMS](/api/sim-management/get-sms-for-sim-using-get/) - [Create SMS](/api/sim-management/send-sms-to-sim-using-post/) - [Get SMS Details](/api/sim-management/get-sms-of-sim-using-get/) - [Delete SMS](/api/sim-management/cancel-sms-for-sim-using-delete/) --- # Volume Limits Source: https://help.1nce.com/api/category/sim-management/volume-limits/ - [Get Global Limits](/api/sim-management/get-limits-using-get/) - [Create Global Limits](/api/sim-management/set-limits-using-post/) - [Get SIM Limits](/api/sim-management/get-selectable-limits-using-get/) --- # Volume Top Up Source: https://help.1nce.com/api/category/sim-management/volume-top-up/ - [Create Single Top Up](/api/sim-management/top-up-using-post/) - [Create Multiple Top Up](/api/sim-management/top-up-multiple-using-post/) - [Enable Auto Top Up](/api/sim-management/auto-topup-using-post/) --- # Service Requests Source: https://help.1nce.com/api/category/support-management/service-requests/ - [Get Service Requests](/api/support-management/get-service-requests-using-get/) - [Create Service Request](/api/support-management/create-service-request-using-post/) --- # Bearer Authorization Source: https://help.1nce.com/api/category/v2/authorization/bearer-authorization/ - [Obtain Access Token](/api/v2/authorization/post-access-token-post/) --- # Connectivity Source: https://help.1nce.com/api/category/v2/sim-management/connectivity/ - [Create Connectivity Reset](/api/v2/sim-management/reset-connectivity-using-post/) --- # General SIMs Source: https://help.1nce.com/api/category/v2/sim-management/general-si-ms/ - [Get All SIMs](/api/v2/sim-management/get-sims-using-get/) - [Get Single SIM](/api/v2/sim-management/get-sim-using-get/) - [Modify SIM card](/api/v2/sim-management/update-sim-using-put/) - [Get SIM Data Quota](/api/v2/sim-management/get-data-quota-for-sim-using-get/) - [Get SIM SMS Quota](/api/v2/sim-management/get-sms-quota-for-sim-using-get/) - [Get SIM Status](/api/v2/sim-management/get-status-for-sim-using-get/) --- # SIM Events Source: https://help.1nce.com/api/category/v2/sim-management/sim-events/ - [Get SIM Events](/api/v2/sim-management/get-events-for-sim-using-get/) --- # SIM Extension Source: https://help.1nce.com/api/category/v2/sim-management/sim-extension/ - [Create SIM Extension](/api/v2/sim-management/extend-sims-using-post/) --- # SMS by ICCID Source: https://help.1nce.com/api/category/v2/sim-management/sms-by-iccid/ - [Cancel SMS](/api/v2/sim-management/cancel-sms-of-sim-using-delete/) --- # SMS Source: https://help.1nce.com/api/category/v2/sim-management/sms/ - [Create SMS](/api/v2/sim-management/send-sms-to-sim-using-post/) - [Get MT/MO-SMS](/api/v2/sim-management/get-sms-for-sim-using-get/) - [Get SMS Details](/api/v2/sim-management/get-sms-of-sim-using-get/) --- # Volume Top Up Source: https://help.1nce.com/api/category/v2/sim-management/volume-top-up/ - [Create Single Top Up](/api/v2/sim-management/top-up-using-post/) - [Enable Auto Top Up](/api/v2/sim-management/auto-topup-using-post/) --- # Get Single Order Source: https://help.1nce.com/api/order-management/get-order-using-get/ `GET /v1/orders/{order_number}` Get a single Order, identified by its order_number. | Name | In | Required | Description | | --- | --- | --- | --- | | order_number | path | true | Order number identifying one specific order. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Get All Orders Source: https://help.1nce.com/api/order-management/get-orders-using-get/ `GET /v1/orders` Get a complete list of all 1NCE orders for the given account. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number index of the requested order list page. Use this parameter to iterate through all orders on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | Defines the size of a page, the number of individual orders listed on one page. The maximum allowed value is 10. | | sort | query | false | Sort the order list by specific keys (order_number, order_status and/or order_date) in a comma seperated list. The default is order_number if no paramter is given. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Order Management Source: https://help.1nce.com/api/order-management/order-management/ Documentation of the 1NCE API for Order Management. - [Get Single Order](/api/order-management/get-order-using-get/) - [Get All Orders](/api/order-management/get-orders-using-get/) - [Create Order](/api/order-management/post-order-using-post/) --- # Create Order Source: https://help.1nce.com/api/order-management/post-order-using-post/ `POST /v1/orders` Trigger an order using a POST request. ```json { "products": [ { "productId": 1001, "quantity": 0 } ], "delivery_address": { "salutation": "1", "first_name": "string", "last_name": "string", "company": "string", "street": "string", "address_line2": "string", "house_number": "string", "zip": "string", "city": "string", "country": "DE", "phone": "string" }, "customer_reference": "" } ``` - `200` — OK - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Get All Products Source: https://help.1nce.com/api/product-information/get-products-using-get/ `GET /v1/products` Get a list of all avaliable products. - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Product Information Source: https://help.1nce.com/api/product-information/product-information/ Documentation of the 1NCE API for Product Information - [Get All Products](/api/product-information/get-products-using-get/) --- # Enable Auto Top Up Source: https://help.1nce.com/api/sim-management/auto-topup-using-post/ `POST /v1/sims/autoTopup` Trigger an auto top up configuration update for the given SIMs. ```json { "enabled": true, "iccids": [ "8988280666000000000" ] } ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Delete SMS Source: https://help.1nce.com/api/sim-management/cancel-sms-for-sim-using-delete/ `DELETE /v1/sims/{iccid}/sms/{id}` Cancel a SMS message that is buffered to be delivered to the device with the SIM card but was not yet delivered. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | id | path | true | The ID of the SMS message to be queried. | - `200` — OK - `204` — No Content - `401` — Unauthorized - `403` — Forbidden - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create SIM Extension Source: https://help.1nce.com/api/sim-management/extend-sims-using-post/ `POST /v1/sims/extension` Trigger the SIM extension for one or more SIM cards to extend their activation period and renew their quota (data and SMS). An invoice is automatically triggered depending on the chosen payment method. | Name | In | Required | Description | | --- | --- | --- | --- | | payment_method | query | false | Optional payment method selection between creditcard, banktransfer, monthly invoice or boleto. If the parameter is left empty or is invalid, banktransfer is used as default for the SIM extension process. To use creditcard please save your credit card details in the customer portal via "account". | ```json { "iccids": [ "8988280666000000000" ], "productId": 0 } ``` - `201` — Created - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Get SIM Connectivity Source: https://help.1nce.com/api/sim-management/get-connectivity-info-for-sim-using-get/ `GET /v1/sims/{iccid}/connectivity_info` Retrieve connectivity information and cell tower of a device with a given SIM. The API call returns valid information when the 1NCE SIM is attached to a 2G/3G network only. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The iccid of the SIM in question. | | subscriber | query | false | Flag indicating if the subscriber information should be retrieved. Default value is true. | | ussd | query | false | Flag for retrieving the USSD connectivity info. Default value is false. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM Data Quota Source: https://help.1nce.com/api/sim-management/get-data-quota-for-sim-using-get/ `GET /v1/sims/{iccid}/quota/data` Get the current data quota of a particular SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM Events Source: https://help.1nce.com/api/sim-management/get-events-for-sim-using-get/ `GET /v1/sims/{iccid}/events` Get diagnostic/event information for a SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | page | query | false | Number index of the requested SIM event page. Use this parameter to iterate through all SIMs on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | The number of events per page, maximum allowed value is 1000. | | sort | query | false | Sort values based on keys that are listed as a comma seperated list, prepend "-" for descending order. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get Global Limits Source: https://help.1nce.com/api/sim-management/get-limits-using-get/ `GET /v1/sims/limits` Get currently configured self-set monthly limits (Data, MT-SMS, MO-SMS) for all SIMs. - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM Limits Source: https://help.1nce.com/api/sim-management/get-selectable-limits-using-get/ `GET /v1/sims/{service}/limits` Get a list of slectable limits for a given service. | Name | In | Required | Description | | --- | --- | --- | --- | | service | path | true | The service name (data, smsMO, smsMT) for which to list the avaliable limit options. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get Single SIM Source: https://help.1nce.com/api/sim-management/get-sim-using-get/ `GET /v1/sims/{iccid}` Get detail information (status, label, MSISDN, IMSI, ICCID, Lifetime, etc.) for a singe SIM based on the ICCID. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get All SIMs Source: https://help.1nce.com/api/sim-management/get-sims-using-get/ `GET /v1/sims` Get a List of SIMs for the current account. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number index of the requested SIM list page. Use this parameter to iterate through all SIMs on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | Defines the size of a page, the number of individual SIMs listed on one page. The maximum allowed value is 100. | | q | query | false | Filter parameter in {filter}:{value} format. Expects comma separated list of filtering criteria out of the following fields:
  • imei
  • ip_address

Example: "ip_address:127.0.0.1,imei:4711"

| | sort | query | false | Sort values in a comma seperated list. Prepend "-" for descending sort. Possible values:
  • imei
  • ip_address

Example:"ip_address,-imei"

| - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get MT/MO-SMS Source: https://help.1nce.com/api/sim-management/get-sms-for-sim-using-get/ `GET /v1/sims/{iccid}/sms` Get a list of SMS sent and received by a specific SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | page | query | false | Number index of the requested SIM SMS page. Use this parameter to iterate through all SIMs on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | The number of SMS messages per page, maximum allowed value is 100. | | sort | query | false | Keys by which the SMS messages should be sorted, listed as comma sperated values. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SMS Details Source: https://help.1nce.com/api/sim-management/get-sms-of-sim-using-get/ `GET /v1/sims/{iccid}/sms/{id}` Query details about an individual SMS from a specifc SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | id | path | true | The ID of the SMS message to be queried. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM SMS Quota Source: https://help.1nce.com/api/sim-management/get-sms-quota-for-sim-using-get/ `GET /v1/sims/{iccid}/quota/sms` Get the current SMS quota of a particular SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM Status Source: https://help.1nce.com/api/sim-management/get-status-for-sim-using-get/ `GET /v1/sims/{iccid}/status` Query the current status of a specific SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Get SIM Usage Source: https://help.1nce.com/api/sim-management/get-usage-for-sim-using-get/ `GET /v1/sims/{iccid}/usage` Query the SIM data and SMS usage over a given period of time. The output is limited to the last 6 months. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | start_dt | query | false | Start date used for the query, format: YYYY-MM-DD | | end_dt | query | false | End date used for the usage query, format: YYYY-MM-DD | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Connectivity Reset Source: https://help.1nce.com/api/sim-management/reset-connectivity-using-post/ `POST /v1/sims/{iccid}/reset` Trigger a connectivity reset for a given SIM. The actual reset will be done asynchronously. A positive-response only means that the connectivity-reset has been successfully placed into the queue. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be reset. | - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create SMS Source: https://help.1nce.com/api/sim-management/send-sms-to-sim-using-post/ `POST /v1/sims/{iccid}/sms` Create and send a MT-SMS towards a device with a 1NCE SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM targeted for the MT-SMS. | ```json { "source_address": "1234567890", "payload": "This is a SMS message.", "udh": "050003CC0301", "dcs": 0, "source_address_type": { "id": 145 }, "expiry_date": "2018-03-14T16:10:29Z" } ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Global Limits Source: https://help.1nce.com/api/sim-management/set-limits-using-post/ `POST /v1/sims/limits` Configure self-set monthly limits for all SIMs (Data, MT-SMS, MO-SMS). ```json { "dataLimitId": 0, "smsMtLimitId": 0, "smsMoLimitId": 0 } ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # SIM Management Source: https://help.1nce.com/api/sim-management/sim-management/ Documentation of the 1NCE API for SIM Management. - [Enable Auto Top Up](/api/sim-management/auto-topup-using-post/) - [Delete SMS](/api/sim-management/cancel-sms-for-sim-using-delete/) - [Create SIM Extension](/api/sim-management/extend-sims-using-post/) - [Get SIM Connectivity](/api/sim-management/get-connectivity-info-for-sim-using-get/) - [Get SIM Data Quota](/api/sim-management/get-data-quota-for-sim-using-get/) - [Get SIM Events](/api/sim-management/get-events-for-sim-using-get/) - [Get Global Limits](/api/sim-management/get-limits-using-get/) - [Get SIM Limits](/api/sim-management/get-selectable-limits-using-get/) - [Get Single SIM](/api/sim-management/get-sim-using-get/) - [Get All SIMs](/api/sim-management/get-sims-using-get/) - [Get MT/MO-SMS](/api/sim-management/get-sms-for-sim-using-get/) - [Get SMS Details](/api/sim-management/get-sms-of-sim-using-get/) - [Get SIM SMS Quota](/api/sim-management/get-sms-quota-for-sim-using-get/) - [Get SIM Status](/api/sim-management/get-status-for-sim-using-get/) - [Get SIM Usage](/api/sim-management/get-usage-for-sim-using-get/) - [Create Connectivity Reset](/api/sim-management/reset-connectivity-using-post/) - [Create SMS](/api/sim-management/send-sms-to-sim-using-post/) - [Create Global Limits](/api/sim-management/set-limits-using-post/) - [Create SIM Transfer](/api/sim-management/sim-transfer-using-post/) - [Create Multiple Top Up](/api/sim-management/top-up-multiple-using-post/) - [Create Single Top Up](/api/sim-management/top-up-using-post/) - [Create Single SIM Configuration](/api/sim-management/update-sim-using-put/) - [Create Multiple SIM Configuration](/api/sim-management/update-sims-using-post/) --- # Create SIM Transfer Source: https://help.1nce.com/api/sim-management/sim-transfer-using-post/ `POST /v1/sims/simTransfer` Trigger a SIM transfer workflow - if possible - for moving SIMs from one customer to another. ```json { "target_organisation": 2000000001, "iccid_ranges": [ { "from": "8988280666000000000", "to": "8988280666000000010" } ], "iccids": [ "8988280666000000000" ] } ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Multiple Top Up Source: https://help.1nce.com/api/sim-management/top-up-multiple-using-post/ `POST /v1/sims/topup` Top up the data/SMS volume of a list of SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | payment_method | query | false | Optional payment method selection between creditcard, banktransfer, monthlyinvoice or boleto. If the parameter is left empty or is invalid, banktransfer is used as default for the top up order process. | ```json [ "8988280666000000000" ] ``` - `201` — Top Up order initiated successfully. - `400` — Bad Request - `401` — Unauthorized - `403` — SIM does not belong to user. - `404` — SIM not found. - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Single Top Up Source: https://help.1nce.com/api/sim-management/top-up-using-post/ `POST /v1/sims/{iccid}/topup` Top up the data/SMS volume of one specific SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be topped up. | | payment_method | query | false | Optional payment method selection between creditcard, banktransfer, monthlyinvoice or boleto. If the parameter is left empty or is invalid, banktransfer is used as default for the top up order process. | - `201` — Order created successfully. - `400` — Bad Request - `401` — Unauthorized - `403` — SIM does not belong to user. - `404` — SIM not found. - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Single SIM Configuration Source: https://help.1nce.com/api/sim-management/update-sim-using-put/ `PUT /v1/sims/{iccid}` Modification of a SIM card to activate, deactivate, change label, change IMEI lock, etc. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be changed. | ```json { "iccid": "8988280666000000000", "label": "DX-137-B12", "imei_lock": false, "status": "Enabled" } ``` - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Multiple SIM Configuration Source: https://help.1nce.com/api/sim-management/update-sims-using-post/ `POST /v1/sims` Change a list of SIMS for activate, deactivate, label, IMEI lock, etc. The actual change will be done asynchronously. A positive-response only means that the SIM changes has been successfully placed into the queue. ```json [ { "iccid": "8988280666000000000", "label": "DX-137-B12", "imei_lock": false, "status": "Enabled" } ] ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Create Service Request Source: https://help.1nce.com/api/support-management/create-service-request-using-post/ `POST /v1/support` Create a new service request towards 1NCE Support. ```json { "replyToMail": "e-mail@address.com", "senderName": "Hans Mustermann", "subject": "Connectivity Issue", "text": "Custom Text" } ``` - `200` — OK - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Get Service Requests Source: https://help.1nce.com/api/support-management/get-service-requests-using-get/ `GET /v1/support` Get a list of all customer service requests. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number index of the requested service request page. Use this parameter to iterate through all service requests on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | The number of service requests per page, maximum allowed value is 100. | - `200` — OK - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Support Management Source: https://help.1nce.com/api/support-management/support-management/ Documentation of the 1NCE API for Support Management. - [Create Service Request](/api/support-management/create-service-request-using-post/) - [Get Service Requests](/api/support-management/get-service-requests-using-get/) --- # API Explorer v2 Source: https://help.1nce.com/api/v2/ # Welcome to the 1NCE API v2 :::info Download YAML Files To download the latest OpenAPI files for the 1NCE API please visit: [/api/v2/](/api/v2/). ::: :::warning 'Try It' Feature Please note that the 'Try It' function can be used only with a valid 1NCE customer account. All queries are made towards the customer account. Be careful with trying out features like orders, top ups, etc. as these API calls will trigger the actual process. ::: Welcome to the 1NCE API v2 documentation. This documentation covers the ins and outs of the API for managing, controlling, and monitoring the 1NCE SIM cards and the related services. As the 1NCE API requires users to authorize in order to use the interface, we strongly suggest starting with the authorization chapters first. The API v2 is structured into different categories: - **Authorization** - Authentication and token management - **SIM Management** - SIM card operations and monitoring If there are any issues or questions regarding the 1NCE services, feel free to contact our [technical support](https://1nce.com/en-eu/support/contact). --- # Authorization Source: https://help.1nce.com/api/v2/authorization/authorization/ Documentation of the authentication used for the 1NCE APIs. - [Obtain Access Token](/api/v2/authorization/post-access-token-post/) --- # Obtain Access Token Source: https://help.1nce.com/api/v2/authorization/post-access-token-post/ `POST /oauth/token` Obtain a token for accessing other 1NCE API resources by using a POST request with a valid username and password combination for a 1NCE user account that has the permission to use the API. ```json { "grant_type": "client_credentials" } ``` - `200` — OK - `400` — Bad Request - `404` — Not Found --- # Enable Auto Top Up Source: https://help.1nce.com/api/v2/sim-management/auto-topup-using-post/ `POST /v2/sims/autoTopup` Trigger an auto top up configuration update for the given SIMs. ```json { "enabled": true, "iccids": [ "8988280666000000000" ] } ``` - `201` — Created - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `422` — The following SIMs are expired and cannot be modified via API. Only extensions are permitted --- # Cancel SMS Source: https://help.1nce.com/api/v2/sim-management/cancel-sms-of-sim-using-delete/ `DELETE /v2/sims/{iccid}/sms/{id}` Cancel a SMS message that is buffered to be delivered to the device with the SIM card but was not yet delivered. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM for MT-SMS or MO-SMS. | | id | path | true | The ID of the SMS message to be cancelled. | - `200` — Resource Deleted - `400` — Bad request - `404` — Not found error - `500` — Internal server error --- # Create SIM Extension Source: https://help.1nce.com/api/v2/sim-management/extend-sims-using-post/ `POST /v2/sims/extension` Trigger the SIM extension for one or more SIM cards to extend their activation period and renew their quota (data and SMS). An invoice is automatically triggered depending on the chosen payment method. | Name | In | Required | Description | | --- | --- | --- | --- | | payment_method | query | false | Optional payment method selection between creditcard, banktransfer, monthly invoice or boleto. If the parameter is left empty or is invalid, banktransfer is used as default for the SIM extension process. To use creditcard please save your credit card details in the customer portal via "account". | ```json { "iccids": [ "8988280666000000000" ], "productId": 0 } ``` - `201` — Created - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found --- # Get SIM Data Quota Source: https://help.1nce.com/api/v2/sim-management/get-data-quota-for-sim-using-get/ `GET /v2/sims/{iccid}/quota/data` Get the current data quota of a particular SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `404` — Not found error - `500` — Internal server error --- # Get SIM Events Source: https://help.1nce.com/api/v2/sim-management/get-events-for-sim-using-get/ `GET /v2/sims/{iccid}/events` Get diagnostic/event information for a SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | | page | query | false | Number index of the requested SIM event page. Use this parameter to iterate through all SIMs on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | The number of events per page, maximum allowed value is 1000. | - `200` — OK - `404` — Not found error - `500` — Internal server error --- # Get Single SIM Source: https://help.1nce.com/api/v2/sim-management/get-sim-using-get/ `GET /v2/sims/{iccid}` Get detail information (status, label, MSISDN, IMSI, ICCID, Lifetime, etc.) for a singe SIM based on the ICCID. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `404` — Not found error - `500` — Internal server error --- # Get All SIMs Source: https://help.1nce.com/api/v2/sim-management/get-sims-using-get/ `GET /v2/sims` Get a List of SIMs for the current account. | Name | In | Required | Description | | --- | --- | --- | --- | | page | query | false | Number index of the requested SIM list page. Use this parameter to iterate through all SIMs on the different pages. The total amount of pages is listed in the response header. | | pageSize | query | false | Defines the size of a page, the number of individual SIMs listed on one page. The maximum allowed value is 100. | | q | query | false | Filter parameter in {filter}:{value} format. Expects comma separated list of filtering criteria out of the following fields:
  • imei
  • ip_address

Example: "ip_address:127.0.0.1,imei:4711"

| | sort | query | false | Sort values in a comma seperated list. Prepend "-" for descending sort. Possible values:
  • imei
  • ip_address

Example:"ip_address,-imei"

| - `200` — OK - `404` — Not found error - `500` — Internal server error --- # Get MT/MO-SMS Source: https://help.1nce.com/api/v2/sim-management/get-sms-for-sim-using-get/ `GET /v2/sims/{iccid}/sms` Get a list of SMS sent and received by a specific SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM for MT-SMS or MO-SMS. | | page | query | false | The number of returned chunk within the complete set. | | per_page | query | false | The numbers of items to return per page. | - `200` — List of MT-SMS and MO-SMS for the device. - `400` — Bad request - `404` — Not found error - `500` — Internal server error --- # Get SMS Details Source: https://help.1nce.com/api/v2/sim-management/get-sms-of-sim-using-get/ `GET /v2/sims/{iccid}/sms/{id}` Query details about an individual SMS from a specific SIM card. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM for MT-SMS or MO-SMS. | | id | path | true | The ID of the SMS message to be queried. | - `200` — Details of the requested SMS. - `400` — Bad request - `404` — Not found error - `500` — Internal server error --- # Get SIM SMS Quota Source: https://help.1nce.com/api/v2/sim-management/get-sms-quota-for-sim-using-get/ `GET /v2/sims/{iccid}/quota/sms` Get the current SMS quota of a particular SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `404` — Not found error - `500` — Internal server error --- # Get SIM Status Source: https://help.1nce.com/api/v2/sim-management/get-status-for-sim-using-get/ `GET /v2/sims/{iccid}/status` Query the current status of a specific SIM card. This API retrieves connectivity details of a SIM. The following is a list of possible statuses: * `ATTACHED`: The Endpoint has successfully attached to the Home Core network in the past. The device will be shown as `ATTACHED` until the visited network has signaled that the device is inactive/offline. Usually the visited network informs the Core Network within 1-2 days after a device went offline. * `ONLINE`: The Endpoint has an active data connection * `OFFLINE`: The Endpoint has not attached to the core network yet or the device was previously attached but the visited network signaled that the device had no activity for the last 1-2 days. Note: The device is not reachable for external services (e.g. SMS, MSRN lookup). * `BLOCKED`: The Endpoint is blocked | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be queried. | - `200` — OK - `400` — Bad request - `404` — Not found error - `500` — Internal server error --- # Create Connectivity Reset Source: https://help.1nce.com/api/v2/sim-management/reset-connectivity-using-post/ `POST /v2/sims/{iccid}/reset` Trigger a connectivity reset for a given SIM. The actual reset will be done asynchronously. A positive-response only means that the connectivity-reset has been successfully placed into the queue. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be reset. | - `201` — No Content - `400` — Bad request - `404` — Not found error - `409` — Operation cannot be completed because the resource is referenced by other resources or otherwise colliding. - `500` — Internal server error --- # Create SMS Source: https://help.1nce.com/api/v2/sim-management/send-sms-to-sim-using-post/ `POST /v2/sims/{iccid}/sms` Create and send an MT-SMS to a device. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM for MT-SMS or MO-SMS. | ```json { "source_address": "1234567890", "payload": "This is an SMS message.", "udh": "050003CC0301", "dcs": 0, "source_address_type": { "id": 145 }, "expiry_date": "2028-03-14T16:10:29.000+00:00" } ``` - `201` — Resource created - `400` — Bad request - `404` — Not found error - `409` — Operation cannot be completed because the resource is referenced by other resources or otherwise colliding. - `500` — Internal server error --- # SIM Management Source: https://help.1nce.com/api/v2/sim-management/sim-management/ Documentation of the 1NCE API for SIM Management. - [Enable Auto Top Up](/api/v2/sim-management/auto-topup-using-post/) - [Cancel SMS](/api/v2/sim-management/cancel-sms-of-sim-using-delete/) - [Create SIM Extension](/api/v2/sim-management/extend-sims-using-post/) - [Get SIM Data Quota](/api/v2/sim-management/get-data-quota-for-sim-using-get/) - [Get SIM Events](/api/v2/sim-management/get-events-for-sim-using-get/) - [Get Single SIM](/api/v2/sim-management/get-sim-using-get/) - [Get All SIMs](/api/v2/sim-management/get-sims-using-get/) - [Get MT/MO-SMS](/api/v2/sim-management/get-sms-for-sim-using-get/) - [Get SMS Details](/api/v2/sim-management/get-sms-of-sim-using-get/) - [Get SIM SMS Quota](/api/v2/sim-management/get-sms-quota-for-sim-using-get/) - [Get SIM Status](/api/v2/sim-management/get-status-for-sim-using-get/) - [Create Connectivity Reset](/api/v2/sim-management/reset-connectivity-using-post/) - [Create SMS](/api/v2/sim-management/send-sms-to-sim-using-post/) - [Create Single Top Up](/api/v2/sim-management/top-up-using-post/) - [Modify SIM card](/api/v2/sim-management/update-sim-using-put/) --- # Create Single Top Up Source: https://help.1nce.com/api/v2/sim-management/top-up-using-post/ `POST /v2/sims/{iccid}/topup` Top up the data/SMS volume of one specific SIM. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be topped up. | | payment_method | query | false | Optional payment method selection between creditcard, banktransfer, monthlyinvoice or boleto. If the parameter is left empty or is invalid, banktransfer is used as default for the top up order process. | - `201` — Order created successfully. - `400` — Bad Request - `401` — Unauthorized - `403` — SIM does not belong to user. - `404` — SIM not found. --- # Modify SIM card Source: https://help.1nce.com/api/v2/sim-management/update-sim-using-put/ `PUT /v2/sims/{iccid}` Modification of a SIM card to activate, deactivate, change label, change IMEI lock, etc. | Name | In | Required | Description | | --- | --- | --- | --- | | iccid | path | true | The ICCID of the SIM to be changed. | ```json { "iccid": "8988280666000000000", "label": "DX-137-B12", "imei_lock": false, "status": "Enabled" } ``` - `200` — No Content - `400` — Bad request - `404` — Not found error - `409` — Operation cannot be completed because the resource is referenced by other resources or otherwise colliding. - `500` — Internal server error --- # Welcome Source: https://help.1nce.com/docs/ > ❗️ **Updated Documentation for Impacted Customers** > > **1NCE GmbH (Germany-based contracting entity)** > >For new customers who purchased their first SIMs on/after **6th October 2025** and whose contracts are managed by 1NCE GmbH. This covers the following countries: >Albania, Austria, Åland Islands, Bosnia and Herzegovina, Belgium, Bulgaria, Switzerland, Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, United Kingdom, French Guiana, Guadeloupe, Greece, Croatia, Hungary, Ireland, Iceland, Italy, Liechtenstein, Lithuania, Luxembourg, Latvia, Monaco, Moldova (Republic of), Montenegro, North Macedonia, Martinique, Malta, Netherlands, Norway, Poland, Portugal, Romania, Serbia, Sweden, Slovenia, Slovakia, San Marino, Ukraine > > → [Continue (Platform v2)](/docs/v2) > > **1NCE Singapore PTE. Ltd. (Singapore-based contracting entity)** > > For new customers who purchased their first SIMs on/after **7th May 2026** and whose contracts are handled via our Singapore entity. This includes the following markets: > >Australia, Bangladesh, Cambodia, China, Hong Kong (China), India, Indonesia, Korea (Republic of), Macau (China), Malaysia, Mariana Islands, Mongolia, Palau, New Caledonia, Philippines, Singapore, Sri Lanka, Taiwan, Thailand, Vietnam > > → [Continue (Platform v2)](/docs/v2) > > **1NCE Japan KK. (Japan-based contracting entity)** > > For new customers who purchased their first SIMs on/after **13 May 2026** and who are from Japan and whose contracts are handled via our Japan entity. > > → [Continue (Platform v2)](/docs/v2/) > > **1NCE Inc. (US-based contracting entity)** > > For new customers who purchased their first SIMs on/after **20 May 2026** and whose contracts are handled via our US entity. This includes the following markets: > > Anguilla, Antigua & Barbuda, Aruba, Bahamas, Barbados, Bermuda, Caribbean Islands, Cayman, Costa Rica, Dominica, Dominican Republic, El Salvador, Greenland, Grenada, Guadeloupe, Guatemala, Honduras, Jamaica, Martinique, Mexico, Panama, Puerto Rico, Trinidad and Tobago, United States > > → [Continue (Platform v2)](/docs/v2/) This is the place to find the detailed technical documentation developers need to start digging into the 1NCE connectivity services. This guide focuses on general knowledge and technical application information for the sim services, connectivity services, platform services, network services, and API reference. If there are any issues or questions regarding the 1NCE services, feel free to contact our technical support (1NCE Contact). We are thankful for suggestions and feedback from our customers as we continue to improve and develop our services. Find the most viewed and recommended documentation chapters in the excerpts below for getting started with 1NCE services. To explore more of the Developer Hub, browse the menu on the left side. For quickly finding specific details, the search function helps to get the needed information. Click on the box header titles to be redirected to the individual chapters. - [Access Point Name (APN)](/docs/connectivity-services/connectivity-services-data-services/data-services-apn/) — Connecting IoT devices using the 1NCE mobile services requires setting the APN. This chapter shows the basics about the Access Point Name used for the 1NCE services. - [API Explorer](/api/) — Check the API Explorer to get to know the Management API and learn more about the usage and the general capacities. - [1NCE Portal Guide](/docs/1nce-portal/portal-dashboard/) — The 1NCE Portal offers an easy-to-use web interface for managing all 1NCE SIMs and related services. The documentation guides show configuration possibilities and features of the 1NCE Portal. - [Data Services](/docs/connectivity-services/connectivity-services-data-services/) — Data Services are essential for connecting devices to linked up cloud services. These guides provide an introduction into the data connectivity with 1NCE SIMs. - [1NCE OS](/docs/1nce-os/1nce-os-services-overview/) — Connecting IoT devices with cloud services like AWS can be challenging. Our 1NCE OS offers several features to easily integrate 1NCE connectivity into cloud services. - [SMS Services](/docs/connectivity-services/connectivity-services-sms-services/) — Many IoT solutions still use SMS for basic configuration and messaging. With the 1NCE products SMS messaging is included. Learn how to use these services. - [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) — Planning to use the SMS Services and receiving messages from SIM devices (MO-SMS) in a publish-subscribe manner? The SMS Forwarder Service offers a Webhook integration to receive Mobile Originated SMS messages on a custom HTTP endpoint. - [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) — All SIM devices generate network event and usage records as part of their normal operation. These events are useful for monitoring and debugging device behavior and usage statistics. Learn more about the 1NCE Data Streamer Service. - [VPN Service](/docs/network-services/network-services-vpn-service/) — The VPN Service offers the passivity to bidirectionally connect to your 1NCE SIM card devices via a private network connection without using the public Internet Breakout. --- # Admin Logs Source: https://help.1nce.com/docs/1nce-os/1nce-os-admin-logs/ As 1NCE OS is intended to ease the entry into IoT applications, the 1NCE Admin Logs provides an aggregator of events from devices and errors. From the Admin Logs, the events and errors can be viewed via the Web Interface or queried using the Management API for further processing. --- # API Examples Source: https://help.1nce.com/docs/1nce-os/1nce-os-admin-logs/admin-logs-api/ The Admin Logs can be accessed via an API to allow customers to get their data in an automated way without going through the portal. The Admin Logs API description is available in the [API Explorer](/api/). *** # Examples ## Get Messages ### Device messages (7 days) Getting all messages for a specific device for 7 days for a device with `ICCID` that is `123456789012345678`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678" ``` The response looks like this: ```json { "items": [ { "id": "2LXBToi1yNaEWTiYYhyGS1AAerg", "customerId": "2000523120", "timestamp": "2023-02-10T09:21:15.634Z", "type": "DEVICE", "message": "Translator[UserPayloadError]", "description": "Asset path:longitude, Error: can't extract [0:8] from 1 bytes", "traceId": "1-63e60c8b-2c5f8668ca294dba54a16820", "category": "error", "imsi": "901408801893721", "ip":"10.209.106.1", "iccid":"123456789012345678", "payloadReference": "2000673166/2LXcToi1yNaEWTiYYhyGS1QBAerg" }, { "id": "2LEc7VjBK3AUtPa00WHQnOfd2cC", "customerId": "2000523120", "timestamp": "2023-02-03T12:50:56.800Z", "type": "LIFECYCLE", "message": "Lifecycle[DeviceFirstTimeRegistered]", "description": "New Device successfully registered for the first time - 8988228066601892721", "traceId": "1-63dd8630-364793628bf27f2b8c3cda07", "category": "info", "ip":"10.209.106.1", "iccid":"123456789012345678", }, ], "page":1, "pageAmount":2 } ``` In the response, one item from the specific device (ICCID “123456789012345678“) is shown. It is an error message coming from the translator service. ### Messages Time Range Getting messages in a specified time range for the same device but between `2022-02-21T13:20:00.000` and `2022-02-21T13:22:00.000`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?startDateTime=2022-02-21T13:20:00.000&endDateTime=2022-02-21T13:22:00.000" ``` Both of the query parameters are optional, but one should be given. If only `startDateTime` is provided, the query will consider the end date-time to be the current time. If only `endDateTime` is provided, the start date-time will be the time seven days ago. ### Working with Pagination By default, up to ten messages are returned from the API. The customer is able to specify the page size with the query parameter pageSize. The value of this parameter should be between 1 and 25. Example call to get a message of an example device in the page of three: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678&pageSize=3" ``` We can also go directly to a certain page by defining the parameter page. We would directly go to page number two with this request: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678&pageSize=3&page=2" ``` ### Calling endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs" ``` With this request you get the last ten messages from all devices within the last seven days. ## Get Message Stats ### Calling Message Stats endpoint To get the message statistics, you need to specify a timezone (mandatory) and you can filter on category if necessary. ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs/stats?timezone=Europe%2FAmsterdam&category=info" ``` With this request you get the statistics for the timezone CET and we set a filter for the category `info`. We would get the following response: ```json { "totalUniqueDevices": 2, "administrationLogs": [ { "amount": 2, "day": "2022-03-07T00:00:00.000+0000" }, { "amount": 2, "day": "2022-03-08T00:00:00.000+0000" } ] } ``` --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-admin-logs/admin-logs-features-limitations/ # Features The Admin Logs provide the possibility to show info messages from lifecycle events and errors from all customer devices. Setting custom filters allows to search for certain messages: * Specific device context using ICCID. * Category: `Info` and `Error`. * Period: 1 day and 7 days. *** # Limitations Admin Logs limitations: * Admin Logs older than 7 days are removed automatically. * Admin Log payload value is saved in binary format. Lifecycle event limitation: * "DEVICE\_FIRST\_TIME\_REGISTERED" event is triggered only once per device, and there are no other configurations available for this. --- # Info category Source: https://help.1nce.com/docs/1nce-os/1nce-os-admin-logs/admin-logs-info-category/ Open the Admin Logs in [1NCE OS](https://portal.1nce.com/portal/customer/connectivitysuite) to see the latest logs from the devices. Use the filter to get Info Category logs. ![](/img/1nce-os/1nce-os-admin-logs/admin-logs-info-category/admin-logs-info.png) ### Lifecycle There is currently one Lifecycle event available. ### DEVICE\_FIRST\_TIME\_REGISTERED * There is only one "DEVICE\_FIRST\_TIME\_REGISTERED" event possible for the device. * The event is triggered on the first interaction of the device with 1NCE OS by interacting with any of endpoints ([UDP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-udp), [COAP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap), [LwM2M](/docs/1nce-os/1nce-os-lwm2m/) registration), [Device Observability Memfault Plugin](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault) or using the [FOTA management Mender Plugin](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender) with a particular device. * Using "DEVICE\_FIRST\_TIME\_REGISTERED" event, customers can identify which devices have been activated and brought online at least once. --- # Web Interface Source: https://help.1nce.com/docs/1nce-os/1nce-os-admin-logs/admin-logs-web-interface/ Open the Admin Logs in [1NCE OS](https://portal.1nce.com/portal/customer/connectivitysuite) to see the latest logs from the devices. At the top, the filter can be used for searching on ICCID, Category or the Time Period. The last 5 Admin Log Events and Errors are shown on the dashboard. ![Filter at the admin logs](/img/1nce-os/1nce-os-admin-logs/admin-logs-web-interface/filter-admin-logs.png) --- # Cloud Integrator Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/
![Cloud Integrator as part of the IoT Integrator](/img/1nce-os/1nce-os-cloud-integrator/IoT-Integrator.png)
The Cloud Integrator allows to create, manage and use 1NCE webhooks and direct AWS integrations. This provides the possibility for a customer to forward data from 1NCE services to customer-defined HTTPS endpoints or an AWS account with real-time information. Forwarded data depends on the selected event type. *** ### Event Types ### Telemetry Data Whenever a message (UDP, CoAP or LwM2M) from a device is sent to the 1NCE OS endpoint(s) the message is forwarded to the customer's Cloud Integrations. * LwM2M messages are forwarded to customer's Cloud Integrations. * Traversed UDP and CoAP messages will be forwarded to customer's Cloud Integrations. The forwarded message content depends on the energy saver status for the specific protocol. If the [Energy Saver](/docs/1nce-os/1nce-os-energy-saver/) is not enabled, then message will be forwarded directly, but when enabled, then a processed message will be forwarded. ### Lifecycle Events This option will forward all the [Lifecycle](/docs/1nce-os/1nce-os-admin-logs/admin-logs-info-category#lifecycle) events from the Info category Admin Logs to the customer's Cloud Integrations. ### Error Events This option will forward all the Error category Admin Logs to the customer's Cloud Integrations. It also will include [Cloud Integration failure event](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event) ### Geofence Events Whenever a geofencing event "EXIT" or "ENTER" has been triggered by device location change the message is forwarded to the customer's Cloud Integrations. ### Location Events Whenever a device GPS location update has been sent using Energy Saver template or CellTower location event has been triggered, the location update event is forwarded to the customer's Cloud Integrations. ### Test Message Test Message can be triggered by [Test AWS Integration](/api/1nce-os/test-aws-integration) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration) endpoints. Test Message will be sent also during integration restart process. Integration restart is being initiated from customer after integration has been set to "INTEGRATION_FAILED". :::info A comprehensive set of examples for each event type can be found [here](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format#examples). ::: --- # AWS Configuration Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/ ## Prerequisites ### Security Token Service (STS) Endpoint In your AWS account the Security Token Service (STS) Endpoint should be enabled for eu-central-1 region.
![STS enabled for eu-central-1 region](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/STS-Endpoint.jpg)
### iot:Data-ATS Endpoint In your AWS account the iot:Data-ATS Endpoint should be enabled for region where you are rolling out AWS Integration.
![iot:Data-ATS Endpoint enabled for the customer’s chosen region](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/IoT-Endpoint.jpg)
### IAM role permissions To successfully roll out the CloudFormation (CFN) stack, the customer must ensure that all the permissions listed in [cfn stack description](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration#cfn-stack-description) are granted. ## Configuration via Frontend For setting up the AWS integration, use the Cloud Integration Wizard in the 1NCE OS portal.\ Click 'New Integration' and select AWS integration as integration type. Use a descriptive name and select the [event types](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format) that you would like to receive.
![Configuration of an AWS Integration in the 1NCE portal](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-aws-creation.png)
Be aware that integration with status ROLLOUT\_STARTED will be created in the Cloud Integrator and you will be taken to AWS to complete the configuration over there.\ This generates a JWT that is only valid for an hour. Once the JWT becomes invalid the rollout has to be restarted. After the configuration click proceed and you will be prompted to go to the AWS console. Continue and now AWS should be open on the 'Quick Create Stack' page. Here you will see things such as the name that was previously given, integration token, etc. If this information is correct, acknowledge AWS requirements and press 'create stack'.
![Creation of AWS stack](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/create-stack-1nceOS.png)
It will take some time for the stack to be created. Nested stacks are shown by the filter option 'view nested' on the top. Once it is done, it should look like this in AWS and 1nceOS portal respectively:
![AWS stack created](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/stack-created-1nceOS.png)
![Integration rolled out](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/rollout-done.png)
### Validate Integration *A device being able to send data is a prerequisite for this step. For more information refer to the cloud integrator[documentation](/docs/1nce-os/1nce-os-cloud-integrator/).* Once your stack has been rolled out, you can test your integration using one of your devices or by using [Test AWS Integration](/api/1nce-os/test-aws-integration) endpoint. In AWS go to the IoT Core service. Navigate to the MQTT test client and subscribe to # as shown below:
![MQTT Test Client](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/MQTT-test-1nceOS.png)
Doing this will subscribe to all topics so if the stack was successfully rolled out, you should see data show up as shown below:
![MQTT Test Client result](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/MQTT-response-1nceOS.png)
If the integration was successfully created, rolled out and actived, *Integration Active* will appear.
![Integration Active](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-active.png)
### Edit AWS integration It is possible to edit the 1nceOS integration options through the front-end by clicking the edit-button as shown below:
![1nceOS change integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/change-configuration.png)
### Restart AWS integration There is a possibility that your integration fails. When this happens, it will be visible in the 1nceOS portal as shown below:
![1nceOS restart integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-restart.png)
By clicking the restart button, there will be an attempt to verify the integration. During that time an event of type TEST\_MESSAGE will be sent out. For more information refer to [event-type documentation](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format) ### Delete AWS Integration There are two ways to delete the integration: #### Front-end You can delete your AWS Integration in the front-end of 1NCE OS or using API. In this case, you need to delete your AWS stack manually.
![1nceOS delete integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/delete-integration.png)
#### AWS When the deletion is initiated from your AWS stack, there are no further actions needed. The callback function will automatically trigger the deletion of the AWS Integration in 1NCE OS.
![AWS delete stack](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/stack-deletion.png)
### CFN stack description The following section describes resources that will be deployed with the stack. Stack contains 3 nested stacks. ### AWS Integration Resource stack #### IAM cross account role Stack creates Cross Account IAM role with following permissions for 1NCE OS AWS account 672401624271: * 'iot:DescribeEndpoint' - Retrieve the AWS IoT endpoint. * 'iot:Publish' - Publish MQTT messages to AWS IoT Core.
![AWS Integration stack resources](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/aws-integration-stack.png)
### Callback stacks Two stacks are rolled out for callback operations: * Callback 'create' stack: Provisions resources required to complete the integration with 1NCE OS. * Callback 'delete' stack: Provisions resources that notify 1NCE OS when the stack is deleted from the customer's AWS account. Both the 'create' and 'delete' stacks provision identical resources.
![Callback ](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/delete-callback-stack2.png)
#### Download code lambda function A Lambda function that downloads the actual callback Lambda function. #### Callback lambda function The 'create' callback stack Lambda function notifies the 1NCE OS that the integration rollout has been successfully completed.\ The 'delete' callback stack Lambda function notifies the 1NCE OS when the CloudFormation stack is deleted from the customer's AWS account. Notifications are sent via API calls. #### S3 bucket S3 buckets where the actual code for the 'create' and 'delete' callback Lambda functions are placed. #### Stack execution IAM Role For each stack execution IAM role with the following permissions is created: Logs: * 'logs:CreateLogGroup' - Allows creation of CloudWatch Log Groups. * 'logs:CreateLogStream' - Allows creation of log streams within the created log groups. * 'logs:PutLogEvents' - Allows publishing log events to the created log streams. Customers S3 bucket: * 's3:DeleteObject' - Allows deletion of objects from the specified S3 bucket. * 's3:GetObject' - Allows reading objects from the specified S3 bucket. * 's3:ListBucket' - Allows listing objects in the specified S3 bucket. * 's3:PutObject' - Allows uploading (writing) objects to the specified S3 bucket. * 's3:GetBucketPolicy' - Allows retrieval of the bucket policy for the specified S3 bucket. * 's3:PutObjectTagging' - Allows adding or updating tags on an S3 object. 1NCE OS S3 bucket: * 's3:GetObject' - Allows reading objects from 1NCE OS S3 bucket. * 's3:GetObjectTagging' - Allows retrieving tags associated with an 1NCE OS S3 object. * 's3:ListBucket' - Allows listing objects in the 1NCE OS S3 bucket. ### Lambda runtime versions used in the different 1NCE OS customer stack versions ##### V1.0.0 * Download code lambda function: python3.9 * Callback lambda function: nodejs14.x ##### V1.1.0 * Download code lambda function: python3.9 * Callback lambda function: nodejs18.x ##### V1.2.0 (latest) * Download code lambda function: python3.13 * Callback lambda function: nodejs22.x --- # Cloud Integration failure event Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/ ## Cloud Integrations failure causes Cloud Integrator service automatically sets customer's AWS or Webhook integrations into the `Failed` state after 5 failed attempts to forward customer message to the AWS or Webhook integration. If integration is set to `Failed` state - an [Admin Log](/docs/1nce-os/1nce-os-admin-logs/) will be generated. Here are some possible failure reasons: * Webhook Integration: - if customer's Webhook destination endpoint is not reachable. - does not return response in 20 seconds. - HTTPS endpoint for some reason starts returning non 2xx response. * AWS IoT Core Integration: - AWS IoT Core outage in the destination AWS Region. - misconfiguration in the customer's AWS Account. ## Cloud Integrations failure monitoring To prevent cases when customer Cloud Integration suddenly gets into the `Failed` state and customer does not notices it for some time, there is possibility to subscribe to `Error` type Admin Logs. It can be done using separate dedicated Webhook or AWS Cloud Integration, where customer can filter out Error events with the type `CloudIntegrator[IntegrationDisabled]`. Following `Error` Cloud Integrator event will be generated with the integration id and name in the `description` field: ```json { "received": "1762351834991", "id": "1-690b5ada-31707a98fb4bf676304a55e2", "type": "ERROR", "error": { "payloadExists": false, "description": "Integration with ID C-_wsByVWIW8PCq4OI82C and name \"Broken_Webhook\" was disabled due to consecutive failed requests. Please review affected integration details in Cloud Integrator.", "id": "353vzrcOpHi4YYbyl0bVYlwURAU", "type": "INTEGRATION", "message": "CloudIntegrator[IntegrationDisabled]" }, "version": "1.0.0" } ``` Also on the 1NCEOS frontend page you will see following Admin Log:
![](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/integration-admin-log.png)
*Integration Failed Admin Log* Following steps should be executed: * Create a dedicated HTTPS endpoint or a separate AWS Account (or region) with AWS IoT Core enabled for monitoring. * Create either Webhook or AWS Integration with only `Error` events type selected. * Implement filtering logic by `type` field on that new Cloud Integration to get notifications in case if type is equal to `CloudIntegrator[IntegrationDisabled]`. ## Restart process In case if it happens customer have to execute following steps: * Check Webhook's HTTPS endpoint or AWS IoT Core configuration in your's AWS Account for any possible reasons why those can return errors. * Trigger restart using one of the possible approaches: - Using following [Restart AWS Integration](/api/1nce-os/restart-aws-integration/) or [Restart Webhook Integration](/api/1nce-os/restart-webhook-integration/) API endpoints. - Restart also can be triggered in the 1NCEOS Cloud Integrator frontend page, see [Restart AWS Integration](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration#restart-aws-integration) --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-features-limitations/ # Features * Receiving LwM2M messages to clients endpoint. * Receiving traversed UDP and CoAP messages to clients endpoint. * In total, there will be five attempts to send the message via Webhook or to AWS with an exponential retry policy (150s, 180s, 420s, 1020s). * Own headers can be specified for webhooks. * Device metadata can be injected in the Webhook's URL and headers. See more details [here](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration#metadata-injection-in-webhook-definitions). * Integrations can be tested by sending TEST_MESSAGE [event type](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format). This can be done by using [Test AWS Integration](/api/1nce-os/test-aws-integration) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration) endpoints. * The "First Successful Message Delivery" timestamp reflects the time of the first successful message sent to the Integration by device after this Integration was created. * In case of Cloud Integration Failure, special Error Admin Log entry will be created, which can be used for monitoring [Cloud Integration failure events](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event). *** # Limitations * Only HTTPS POST webhook endpoints are supported. Endpoints should respond with 2xx HTTP status code. * Customer endpoint should respond within 20s. * Same customer endpoint URL **CANNOT** be set to multiple webhooks simultaneously. * Integrations will be set to state `integration failed` after 5 unsuccessful message forwarding attempts. If needed, they can be restarted manually. * "First Successful Message Delivery" value will be updated only on first successfull message sent by device after Integration is created/rolled out. * Integration state will not be changed if a test message will be sent to the integration. * Customer webhook endpoints with self-signed certificate are not supported. * Customer webhook endpoint domains with special characters are not supported. In case special characters should be used, please refer to `punycode`. * Data is sent in JSON-Format: * For all LwM2M Messages. * For all UDP and CoAP messages that are being processed with Energy Saver template. * If `Parse JSON payload` is enabled and that message is a valid parsable JSON. * Data is sent in Base64 format: * If `Parse JSON payload` is disabled. * If `Parse JSON payload` is enabled but that message is NOT a valid parsable JSON. * Only device metadata can be injected into a webhook's definition, such as :iccid:, :imsi: and :ip: --- # Output Format Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/ ## AWS Integration MQTT Topics For AWS Integrations the messages will be forwarded to a dedicated AWS IoT Core MQTT topic for each event type. | Event Type | AWS IoT Core MQTT Topic | | --- | --- | | ERROR | `error` | | GEOFENCE | `geofence` | | LOCATION | `location` | | LIFECYCLE | `lifecycle` | | TELEMETRY_DATA | LWM2M & UDP protocol: `{{iccid}}/messages` CoAP protocol with provided [query parameter _t_](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap): `{{iccid}}/{\{query\_parameter\_t}}` CoAP protocol without provided [query parameter _t_](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap): `{{iccid}}` | | TEST_MESSAGE | `integration-status` | *** ## Examples ### TELEMETRY_DATA ```json { "payload": { "type": "JSON", "value": { "latitude": 7.490929188596135e+247, "longitude": 2.586343401687847e+161 } }, "received": "1670598749915", "id": "1-6393505d-67fa8489fb9c791fcddd43f0", "source": "UDP", "type": "TELEMETRY_DATA", "version": "1.0.0", "device": { "iccid": "8988280666000002864", "ip": "100.91.200.24", "imsi": "901405100002864" } } ``` ### LIFECYCLE ```json { "lifecycle": { "type": "DEVICE_FIRST_TIME_REGISTERED", "message": "New Device successfully registered for the first time - 8988280666000002864" }, "received": "1670830184814", "id": "1-6396d868-d00f68b911b75bc761768e9b", "type": "LIFECYCLE", "version": "1.0.0", "device": { "iccid": "8988280666000002864", "ip": "100.91.200.24", "imsi": "901405100002864" } } ``` ### ERROR ```json { "id": "1-87654321-4fff5fb82c196babcd00008", "type": "ERROR", "received": "1649931594333", "device": { "iccid": "1234567890123456789", "imsi": "987654321098765", "ip": "127.0.0.1" }, "error": { "id": "3dsd627637267sahdgyasd", "type": "DEVICE", "message": "Translator[UserPayloadError]", "description": "Asset path:Temperature, Error: can't extract [200:201] from 2 bytes", "payloadExists": true }, "version": "1.0.0" } ``` ### GEOFENCE ```json { "id": "1-87654321-4fff5fb82c196babcd00007", "type": "GEOFENCE", "received": "1649931594333", "geofence": { "id": "Wg9ys5VqmSNN8M8YN2rv8", "name": "TEST_GEOFENCE_1", "coordinates": ["24.166234790073986","56.977086867785"], "source": "CellTower", "type": "EXIT" }, "device": { "ip": "100.91.200.20", "iccid": "1234567890123456789", "imsi": "987654321098765" }, "version": "1.0.0" } ``` ### LOCATION ```json { "id": "1-87654321-4fff5fb82c196babcd00007", "type": "LOCATION", "received": "1649931594333", "location": { "source": "CellTower", "coordinates": ["24.166234790073986","56.977086867785"], "metadata": { "verticalAccuracy": 45, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 303, "horizontalConfidenceLevel": 0.68 } }, "device": { "ip": "100.91.200.20", "iccid": "1234567890123456789", "imsi": "987654321098765" }, "version": "1.0.0" } ``` :::warning Note that `metadata` parameter with accuracy data is only available in **Plus** CellTower locator mode. ::: ### TEST_MESSAGE This event can be triggered by [Test AWS Integration](/api/1nce-os/test-aws-integration) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration) endpoints. This event will be triggered also if an integration with status `INTEGRATION_FAILED` will be restarted. ```json { "id": "1-63d889d3-d987cbb90f8f10c76278d8dd", "type": "TEST_MESSAGE", "received": "1675135445411", "integration": { "id": "X8qB3FhJQyffUH0GqL3gC", "name": "integration-name" }, "version": "1.0.0" } ``` *** # Message Properties These are the properties of a message. It contains parameters that help to identify the message and the device that has sent the message. | Property | Data Type | Description | Present in event types. *Optional | | :---------- | :---------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | | type | ENUM | Source event type. Values: `LIFECYCLE`, `TELEMETRY_DATA`, `ERROR`, `GEOFENCE`, `TEST_MESSAGE` | All | | received | STRING | UNIX Timestamp. Received message date and time in milliseconds since midnight, January 1, 1970 UTC. | All | | source | ENUM | Values: `UDP`, `COAP`, `LWM2M` | TELEMETRY_DATA | | version | STRING | Version number of our Payload-Format. With new version, format can change. | All | | id | STRING | Unique ID for each message sent. | All | | device | JSON Object | Object describing device from which the message was received. | TELEMETRY_DATA, GEOFENCE, LIFECYCLE, *ERROR, LOCATION | | payload | JSON Object | Object describing message payload. | TELEMETRY_DATA | | lifecycle | JSON Object | Lifecycle object. | LIFECYCLE | | error | JSON Object | Object describing error. | ERROR | | geofence | JSON Object | Object describing geofence event. | GEOFENCE | | integration | JSON Object | Object describing integration. | TEST_MESSAGE | | location | JSON Object | Object describing location. | LOCATION | *** # Payload Properties These are the properties of a message payload object. It contains message payload properties. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------------- | | type | ENUM | Values: `JSON`, `STRING` | | encoding | ENUM | Present only for UDP and COAP raw messages that hasn't been traversed through translation service. Values: `base64`. | | value | see type | Payload value. | | topic | STRING | Present only for COAP messages. | *** # Device Properties These are the properties of a message device object. It contains parameters that help to identify the device that has sent the message. | Property | Data Type | Description | | :------- | :-------- | :--------------------------------- | | iccid | STRING | Device iccid. | | imsi | STRING | Device imsi1. | | ip | STRING | Device ip address in 1nce network. | *** # Lifecycle properties These are the properties for lifecycle events and it is present only for lifecycle messages. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | type | ENUM | Values: `DEVICE_FIRST_TIME_REGISTERED` | | message | STRING | Description of lifecycle event | # Error properties These are the properties of a message error object. It is present only for error messages. | Property | Data Type | Description | | :------------ | :-------- | :----------------------------------------------------- | | id | STRING | Error id | | type | ENUM | Values: `DEVICE`, `GENERAL`, `INTEGRATION`, `LOCATION` | | message | STRING | Short error message | | description | STRING | Detailed error description | | payloadExists | BOOLEAN | Does Error contains payload | # Geofence properties These are the properties of a message geofence object. It is present only for geofence messages. | Property | Data Type | Description | | :---------- | :----------- | :--------------------------------------------------------------------------------------- | | id | STRING | Geofence id | | type | ENUM | Values: `EXIT`, `ENTER` | | name | STRING | Name of geofence | | coordinates | STRING ARRAY | Coordinate of location which triggered the geofence event [ longitude, latitude ] | | source | ENUM | Values: `GPS`, `CellTower` | # Integration properties These are the properties of a message integration object. | Property | Data Type | Description | | :------- | :-------- | :------------------ | | id | STRING | Integration id | | name | STRING | Name of integration | # Location properties These are the properties of a message location object. It is present only for location messages. | Property | Data Type | Description | | :---------- | :----------- | :--------------------------------------------------------------------------------------- | | source | ENUM | Values: `GPS`, `CellTower` | | coordinates | STRING ARRAY | Coordinate of location which triggered the location event [ longitude, latitude ] | | metadata | OBJECT | **Optional** JSON field with position metadata like vertical accuracy, country, etc | --- # Webhook Configuration Source: https://help.1nce.com/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/ To start using the Cloud Integrator with webhook integration, an HTTPS endpoint should be created. The endpoint could be either an IP address or a domain name. Depending on the customer's network security - it is possible\ that the webhook source IPs should be whitelisted. The following IPs will forward data to the webhook endpoint(s): * 52.29.71.11 * 18.157.211.95 # Configuration via Frontend ## Webhook Creation To create a webhook you should at least define an own integration name and an endpoint URL. Further fields that can be specified are: * [Event Types](/docs/1nce-os/1nce-os-cloud-integrator/#event-types) to listen to. * Custom HTTP headers for webhooks. * Whether non-translated messages should be parsed to JSON, if possible.
![Configuration of a Webhook in the Frontend](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/webhook-creation.png)
# Webhook Configuration via API ## Webhook Creation * Headers object in the request body should contain authorization and configuration headers that are expected by the customer's endpoint. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "webhook-name-1", "url": "https://www.your-endpoint.com/messages1", "headers": {"x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}, "eventTypes": [{ "type": "TELEMETRY_DATA" }] }' ``` ### Metadata Injection in Webhook Definitions Webhook definitions support metadata injection in the `url` and `headers` fields using placeholders.\ These placeholders will be automatically replaced with data from the device that triggered the event, such as telemetry\ data or location events. The following placeholders can be used in the `url` and `headers` fields: | Placeholder | Description | Default Value (if unavailable) | | ----------- | ------------------------ | ------------------------------ | | `:iccid:` | ICCID of the device | `none` | | `:imsi:` | IMSI1 of the device | `none` | | `:ip:` | IP address of the device | `none` | :::info If an event does not contain the required data, the corresponding placeholder will be replaced with `none` ::: :::warning If a webhook definition contains an unsupported placeholder, it will remain unchanged. ::: #### Examples Consider the following webhook configuration: ```json { "name": "webhook-name-1", "url": "https://www.your-endpoint.com/events?iccid=:iccid:&ip=:ip:&imsi=:imsi:", "headers": { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": ":imsi:", "x-device-iccid": ":iccid:", "x-device-ip": ":ip:" }, "eventTypes": [{ "type": "TELEMETRY_DATA" }] } ``` #### Scenario - Full Device Metadata Injection For an event coming from a device with the following attributes: * **ICCID**: `1234567890123456789` * **IMSI**: `987654321098765` * **IP**: `192.168.1.1` The webhook request will be transformed as follows: * **URL:**\ `https://www.your-endpoint.com/events?iccid=1234567890123456789&ip=192.168.1.1&imsi=987654321098765` * **Headers:** ```json { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": "987654321098765", "x-device-iccid": "1234567890123456789", "x-device-ip": "192.168.1.1" } ``` #### Scenario - Missing Metadata For an admin log event that is unrelated to a specific device, no metadata can be injected an the placeholders will be\ replaced with `none`. The webhook request will be transformed as follows: * **URL:**\ `https://www.your-endpoint.com/events?iccid=none&ip=none&imsi=none` * **Headers:** ```json { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": "none", "x-device-iccid": "none", "x-device-ip": "none" } ``` #### Scenario - Unsupported Placeholders If a webhook definition contains an unsupported placeholder, it will remain unchanged. ```json { "name": "webhook-name-2", "url": "https://api.example.com/data?destination=:unknown:", "headers": { "x-tracking": ":tracking_id:" } } ``` Since `:unknown:` and `:tracking_id:` are not supported, the resulting webhook request will be: * **Final URL:** `https://api.example.com/data?destination=:unknown:` * **Headers:** ```json { "x-tracking": ":tracking_id:" } ``` ## Get all Integrations ```curl curl --location --request GET 'https://api.1nce.com/management-api/v1/integrate/clouds' ``` Response Example: ```json { "page":1, "pageAmount":1, "items": [ { "id":"AP3dIUs3c7_Oo2yJYaXWg", "name":"test_integration", "state":"INTEGRATION_FAILED", "type":"WEBHOOK", "createdTime":"2022-11-22T12:16:30.814Z", "updatedTime":"2022-11-23T08:07:19.354Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" }, { "type":"TELEMETRY_DATA", "version":"1.0.0" } ] }, { "id":"Jv2cS-pPcy0NdtQ64ycZJ", "lastSuccessfulMessageDelivery":"2022-12-07T12:29:51.927Z", "name":"beeceptor-webhook-int", "state":"INTEGRATION_ACTIVE", "type":"WEBHOOK", "createdTime":"2022-09-16T11:01:11.390Z", "updatedTime":"2022-12-09T11:23:48.609Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" }, { "type":"TELEMETRY_DATA", "version":"1.0.0" } ] }, { "id":"MzSca5vvHAfJ4MUUCfCGb", "name":"rollout-started-int", "state":"ROLLOUT_STARTED", "type":"AWS", "createdTime":"2022-10-17T13:30:15.309Z", "updatedTime":"2022-10-17T13:30:15.309Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" } ] } ] } ``` ## Integration Edit To edit your webhook integration via API, you can use following curl request: ```curl curl --request PATCH \ --url https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId} \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data ' { "eventTypes": [ { "type": "LIFECYCLE" } ], "url": "www.example.com", "jsonPayloadEnabled": false } ' ``` ## Test Integration To send test message to your webhook integration via API, you can use following curl request: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/test' ``` :::info Any metadata injection placeholder will resolve to `none` ::: :::info This functionality does not update "First Successful Message Delivery" field value. ::: ## Integration Restart After 5 unsuccessful message attempts for a webhook it will be set to state `INTEGRATION_FAILED`. To restart the webhook: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/restart' ``` :::info Any metadata injection placeholder will resolve to `none` ::: :::info This functionality does not update "First Successful Message Delivery" field value. ::: --- # Device Authenticator Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-authenticator/ ![](/img/1nce-os/1nce-os-device-authenticator/device-authenticator.png) ## Device Authenticator The Device Authenticator offers a secure and automatic onboarding service for devices. The Device Authenticator is based on the Sim-as-an-Identity principle. Through unique identifiers, each SIM Card is securely authenticated and can be immediately used to send data to the [device integrator](/docs/1nce-os/1nce-os-device-integrator/). ## Sim-as-an-Identity The `ICCID` of the customer SIM is used as a unique identifier for the device. --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-authenticator/device-authenticator-features-limitations/ ## Features The Device Authenticator solution is part of 1NCE OS and allows customers a seamless and fully automated device onboarding. ## Limitations The Device Authenticator works only with enabled Breakout regions, which currently include Europe (Frankfurt) and US East (N. Virginia). For more details, see [Internet Breakout](/docs/network-services/network-services-internet-breakout). ## Security Security is the highest focus for the Device Authenticator. Each SIM Card is authenticated by the 1NCE core network using unique identifiers like IMSI, MSISDN and IMEI (if the IMEI Lock is activated by the customer). Additionally, the static, private IP addresses is used in the 1NCE core network to identify and check each data package processed by 1NCE OS to validate the authentication of the device. To keep the devices functional and authenticated it should remain with the same SIM. Further security is guaranteed through an encrypted communication between the device and 1NCE OS using DTLS for CoAP or LwM2M. --- # Device Controller Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-controller/ The Device Controller supports sending messages to the device via the 1NCE OS managed services. For that we offer three protocols in Device Integrator.
![Device Controller as part of the IoT Integrator](/img/1nce-os/1nce-os-device-controller/IoT-Integrator.png)
--- # API Examples Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-controller/device-controller-api/ The Device Controller can be accessed via an API to allow customers to send data to the devices in an automated way without going through the portal.\ The Device Controller API description is available in the [API Explorer](/api/). # Examples ## Create Action Request An action request can include different fields per protocol. Therefore, an example request body is given for every protocol. ### UDP Creating UDP action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/UDP" ``` The request body looks like this: ```json { "payload": "Data to send to the device", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" } ``` ### CoAP Creating CoAP action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/COAP" ``` The request body looks like this: ```json { "payload": "Data to send to the device", "payloadType": "STRING", "port": 3000, "path": "/example?param1=query_param_example", "requestType": "POST", "requestMode": "SEND_NOW" } ``` ### LwM2M Creating LwM2M action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/LWM2M" ``` The request body looks like this: ```json { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "requestMode": "SEND_WHEN_ACTIVE" } ``` ### Bulk request Creating LwM2M action request for multiple devices: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/actions/LWM2M" ``` The request body looks like this: ```json { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "requestMode": "SEND_WHEN_ACTIVE", "deviceIds": ["123456789012345678", "123456789012345679", "123456789012345680"] } ``` ### Retry Mechanism When submitting an action request with `SEND_WHEN_ACTIVE` mode, the user can specify the parameter `sendAttempts` in\ the request body to restrict how many times the device controller can attempt to send the data to the device. \ If all attempts fail, then the action request will be permanently marked with the status `FAILED`. The `sendAttempts` parameter is optional and, if unspecified, defaults to 1. \ The maximum number of allowed retries is 5. :::warning Please note that this functionality is **NOT supported by the UDP protocol**. ::: ### Request Body Properties These are the properties of a request body. It specifies when and which message will be sent to the device. | Property | Data Type | Description | Available for protocol. \*Optional | | :-------------- | :-------- | :------------------------------------------------------------------------------------------- | :--------------------------------- | | payload | STRING | Data to send to the device. | UDP, \*CoAP | | payloadType | ENUM | Type of the payload. Values: `STRING`, `BASE64`. | UDP, \*CoAP | | port | INTEGER | Communication port number of a device. | UDP, CoAP | | requestMode | ENUM | Values: `SEND_NOW`, `SEND_WHEN_ACTIVE` (when a device sends a message). Default: `SEND_NOW`. | \*UDP, \*CoAP, \*LwM2M | | path | STRING | Absolute path to the resource. | CoAP | | requestType | ENUM | Method used to send message. Values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. | CoAP | | action | ENUM | LwM2M action name. Values: `read`, `write`, `execute`, `observe-start`, `observe-end`. | LwM2M | | resourceAddress | STRING | LwM2M OMA object resource address. | LwM2M | | data | STRING | Data to send to the device. | \*LwM2M | | sendAttempts | INTEGER | The maximum number of attempts to send data to the device. Default: 1 | \*CoAP, \*LWM2M | *** Note that for LwM2M there's no possibility to provide a data type for the `data` property. For LwM2M we support 8 data types: TIME, STRING, BOOLEAN, INTEGER, FLOAT, UNSIGNED\_INTEGER, OBJLINK and OPAQUE. The data type depends on the addressed resource. Users should provide the data in a stringified format (base64 encoded string for OPAQUE). In case an invalid data type for a resource is used, an Admin Log will be created. ### Response The API will accept the request with a `202 Accepted` response code and a response body containing two properties: id (string) and message (string). The id can be used to track the status of the request or cancel the request (see examples below). The message property contains a confirmation message about the request created. Example: ```json { "id": "trxHeBL0d234fsfds", "message": "Action read for resource /3/45/22 successfuly scheduled for device 123456789012345678." } ``` ## Get action request(s) Get action request(s) endpoints are available to track the status of the request and potentially see the response from a device using CoAP/LwM2M. The `requestData` property return protocol-specific request data provided when the request was created. For LwM2M the `responseData` can contain the following properties if available: `code` (response code), `payload` (data from the device), for Coap there is also additional field - `payloadType` (payload type). The `payloadType` is either `TEXT` when the response content format is printable, or `BASE64` if the content format is not printable or not present at all. In case an error occurs, the field `errorMessage` is present in the `responseData`. ### By specific requestId Getting request with id `trxHeBL0d234fsfds`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds" ``` The response could be `200 OK` with body: ```json { "id": "trxHeBL0d234fsfds", "status": "SUCCEEDED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "LWM2M", "created": "2024-08-22T11:14:28.157Z", "updated": "2024-08-22T11:14:28.157Z", "mode": "SEND_WHEN_ACTIVE", "resultData": { "code": "205", "payload": "Data from the device", "payloadType": "TEXT" }, "requestData": { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "iccid": "123456789012345678", "imsi1": "456789012345678", "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1", "deviceId": "123456789012345678", "requestId": "trxHeBL0d234fsfds", "customerId": "1234567890", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1" }, "sendAttemptsLeft": 0, "sendAttempts": 3 } ``` For LwM2M `resultData` could be ```json { "resultData": { "code": "205", "payload": "Data from the device" } } ``` For CoAP `resultData` printable text: ```json { "resultData": { "code": "205", "payload": "Data from the device", "payloadType": "TEXT" } } ``` For CoAP `resultData` binary text: ```json { "resultData": { "code": "205", "payload": "RGF0YSBmcm9tIHRoZSBkZXZpY2U=", "payloadType": "BASE64" } } ``` ### By using the optional filter query parameters There are 2 endpoints available that support query parameters and are meant to query action requests by different statuses: [Active action requests](/api/1nce-os/get-active-device-action-requests) are those which have statuses `IN_PROGRESS `and `SCHEDULED` [Archived action requests](/api/1nce-os/get-archived-device-action-requests) are those which have statuses `CANCELLED`,`FAILED` and `SUCCEEDED` Getting multiple **archived** requests with optional filters (query parameters) specified. For example, to get all LwM2M action requests that succeeded for a device with id 123456789012345678:: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/archived?protocol=LWM2M&deviceId=123456789012345678&status=SUCCEEDED" ``` The response could be `200 OK` response code with body: ```json { "items": [ { "id": "2l0mG3WulN1SUvlIcHjvKXBeZk0", "status": "SUCCEEDED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "LWM2M", "created": "2024-08-22T11:14:28.157Z", "updated": "2024-08-22T11:14:28.157Z", "mode": "SEND_WHEN_ACTIVE", "resultData": { "code": "205", "payload": "Data from the device" }, "requestData": { "data": "Data to send to the device", "iccid": "123456789012345678", "imsi1": "456789012345678", "action": "write", "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1", "deviceId": "123456789012345678", "requestId": "2l0mG3WulN1SUvlIcHjvKXBeZk0", "customerId": "1234567890", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1", "resourceAddress": "/3311/0/5850" }, "sendAttemptsLeft": 0, "sendAttempts": 3 } ], "page": 1, "pageAmount": 1 } ``` Getting multiple **active** requests with optional filters (query parameters) specified. For example, to get all UDP action requests that are scheduled for a device with id 123456789012345678:: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/active?protocol=UDP&deviceId=123456789012345678&requestMode=SEND_WHEN_ACTIVE" ``` The response could be `200 OK` response code with body: ```json { "items": [ { "id": "2l0kyyq0zGSuc1C78NKe5Pc3Auk", "status": "SCHEDULED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "UDP", "created": "2024-08-22T11:03:59.267Z", "updated": "2024-08-22T11:03:59.267Z", "mode": "SEND_WHEN_ACTIVE", "requestData": { "port": 4343, "iccid": "123456789012345678", "imsi1": "456789012345678", "payload": "Hello world", "traceId": "1-66c71b1f-64f6213bb0ea04d2f5784494", "deviceId": "123456789012345678", "requestId": "2l0kyyq0zGSuc1C78NKe5Pc3Auk", "customerId": "1234567890", "payloadType": "STRING", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1" }, "sendAttemptsLeft": 1, "sendAttempts": 1 } ], "page": 1, "pageAmount": 1 } ``` ## Delete action request(s) The delete endpoint is used the cancel requests. This means `SCHEDULED` requests will be updated to the status `CANCELLED`. The messages will not be sent to the device. ### By specific requestId Delete request with id `trxHeBL0d234fsfds`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds" ``` The response could be `200 OK` response code with body: ```json { "id": "trxHeBL0d234fsfds", "status": "CANCELLED" } ``` ### By deviceId Delete all requests for device with id `123456789012345678`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/requests" ``` The response could be `200 OK` response code with body: ```json [{ "id": "trxHeBL0d234fsfds", "status": "CANCELLED" }] ``` --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-controller/device-controller-features-limitations/ # Features * Sending messages to IoT devices using UDP, CoAP and LwM2M. * Message for single device and [bulk devices](/docs/1nce-os/1nce-os-device-controller/device-controller-api#bulk-request) are supported. * Schedule message to be send when we receive a message from the device or on LwM2M registration and update events (requestMode `SEND_WHEN_ACTIVE`) * Cross-protocol trigger: sending a message from the device with any protocol to the 1NCE OS endpoint will trigger sending scheduled messages for all protocols to the device * Possibility to cancel a scheduled request * Possibility to cancel all scheduled requests for a device * See the response from the device for CoAP and LwM2M * Possibility to configure [retries](/docs/1nce-os/1nce-os-device-controller/device-controller-api#retry-mechanism) for scheduled CoAP or LwM2M messages. * Track the status of action requests. Available values: * `SCHEDULED`: the request was created with requestMode `SEND_WHEN_ACTIVE`. The request hasn't been sent to device and is still pending for a trigger to occur. * `IN_PROGRESS`: the request was created with requestMode `SEND_NOW`, or was scheduled and a trigger occurred * `SUCCEEDED`: device responded with 2.xx response code via CoAP or LwM2M. Or message was sent via UDP (there's no validation a message via UDP was received). * `FAILED`: device responded with 4.xx or 5.xx response code via CoAP or LwM2M. Or an unexpected error occurred. Check the `resultData` of the request for more details. Only for CoAP, if the actual response data fails to be saved (e.g. malformed payload), then the Action request finishes with a `FAILED` state. * `CANCELLED`: a scheduled request was cancelled via the DELETE endpoints of our API
![Action request lifecycle](/img/1nce-os/1nce-os-device-controller/device-controller-features-limitations/device-controller.png)
*** # Limitations :::warning For CoAP Actions the device should send ACK to Device Controller IP from which the message was received **instead of sending ACK to[CoAP Server](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap)** ::: * A maximum of 10 Messages can be scheduled per device * Maximum 100 devices are allowed to be selected for each request * Scheduled messages (requestMode `SEND_WHEN_ACTIVE`) are expired and sent to `FAILED` status if not triggered during 24 hours * Requests will be deleted 7 days after the creation date, independent of the status of the request. * A maximum UDP payload size of 508 bytes * A maximum CoAP payload size of 1024 bytes * CoAP DTLS is currently not supported * The maximum number of send attempts for SEND_WHEN_ACTIVE requests is 5. * For CoAP Actions only, the response body (if available) will be visible as either a plain string or a Base64 encoded value, depending on the Content-Format of the response. If no Content-Format is provided, then Base64 is the default one. * According to [RFC7252 section 4.8](https://www.rfc-editor.org/rfc/rfc7252.html#section-4.8), the end timeout for a CoAP message with default retransmission (maximum 4 retransmits) and exponential backoff can range from approximately 62 to 93 seconds. * To successfully reach device from 1NCE OS, ensure that the account is configured with the appropriate allowed Breakout network settings, which currently include Europe (Frankfurt) and US East (N. Virginia). For more details, see [Internet Breakout](/docs/network-services/network-services-internet-breakout) --- # Web Interface Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-controller/device-controller-web-interface/ The device controller is available in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal, by opening the device controller tab. ## Sending Data to device On device controller page, table with the device list is shown. Filtering by Device ID (ICCID) is available in the table.
![Device controller devices table with filtering](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/devices-table-filtering.png)
By clicking on a specific device in the table a wizard will be opened that allows: * Sending UDP message to the device * Sending `POST`, `PUT`, `DELETE`, `PATCH` or `GET` CoAP request to the device. * Triggering `Read`, `Write`, `Execute`, `Observe-start` or `Observe-end` LwM2M action to the device
![Device controler UDP request creation view](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/new-request-udp.png)

Device controller UDP request creation view

### Request Mode #### Send Now Request mode `SEND_NOW` will send the data to the device immediately. It will be validated if device is currently registered to LwM2M server, if LwM2M protocol will be selected. If device is not registered to LwM2M server an error toaster will be shown.
![Device not registered to LwM2M server](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/Not-registered-to-lwm2m-server.png)
For CoAP and LwM2M messages wizard will wait for the response and display the response details.
![Device controler waiting for response](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/coap-waiting-for-response.png)

Device controller waiting for response

![LwM2M Response Details](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/LwM2M-Success-Response.png)
:::warning Please note that **Response wizard is not present for UDP messages due to UDP specifics**. ::: #### Send when device is active Request mode `SEND_WHEN_ACTIVE` will schedule the message and send the data to device when it will become active. Scheduled messages will be sent out on `Cross-protocol trigger` or `LwM2M registration and update events` as decribed in the [device controller features](/docs/1nce-os/1nce-os-device-controller/device-controller-features-limitations). In this request mode it is possible to configure `Send Attempts` for CoAP and LwM2M protocols. For failed messages [retry mechanism](/docs/1nce-os/1nce-os-device-controller/device-controller-api#retry-mechanism) will be applied if required.
![Send attempts configuration](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/send-attempts.png)
:::warning Please note that **Send attempts are NOT supported for the UDP protocol**. ::: ## Requests ### Requests history In the device controller, the tables with active and archived requests history are available. Archived request history is stored for 7 days and active request history is stored for 1 day. It is possible to filter the requests by the following parameters: * Request Id * ICCID (Device Id) * Request Status * Active requests table: (`Scheduled`, `In progress`) * Archived requests table: (`Failed`, `Succeeded` or `Canceled`) * Protocol (`UDP, CoAP` or `LwM2M`)
![Device controller requests table with filtering](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/requests-table-filtering.png)
### Request Details By clicking on a specific request the request details will be displayed. In the request details some fields are mandatory for every request. Depending on protocol and request mode some fields could be optional: #### Mandatory fields ##### Request: * Request Id * Status of the request * Protocol * Request Mode * Request Creation Time * Request Last Update Time * Request Data ##### Device: * Device Id (ICCID) * IP Address #### Optional fields * Configured send attempts * Left send attempts * Result Data
![Request details](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/request-details.png)
### Canceling a request It is possible to cancel a request form Request Details. This is possible only for "Scheduled" requests.
![Canceling a request](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/cancel-request.png)
--- # Device Inspector Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-inspector/ ![](/img/1nce-os/1nce-os-device-inspector/device-inspector.png) The 1NCE Device Inspector as part of the 1NCE OS allows customers to seamlessly manage of all SIM devices existing in the 1NCE Portal Organization. The management makes transparent use of the SIM-as-an-Identity service in the background to reference a digital representation of each individual device with a 1NCE SIM. The Device Inspector combines an interface for analytics and monitoring. Possible use cases are: * Viewing the current digital state representation of a SIM device. * Browsing through the history of states of a SIM device. * Performing analytics or monitoring activities on their devices. --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/ ## Features The device inspector overview provides a list of all customer devices. The list can be filtered by `ICCID` to search for a specific device. To see more information of a certain device, a single device can be select it in the list.
![Device Inspector overview](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-filter.png)
The details will provide more specific information. ### State Device state for UDP, CoAP or LwM2M messages. * UDP or CoAP . Last message received from the device is stored in the state. By default, the portal tries to convert Base64 messages to JSON format. If the received content is not valid JSON, the portal will display the original message as Base64. If the user has enabled the **energy saver** feature with a valid template for transforming payload into JSON, the portal will display message as a JSON and, if the message is not tranformable with the existing **energy saver** template, there will be an admin log created with the error message. For CoAP messages, the topic is also stored in the device state. * LwM2M. Digital representation from the device is stored in state according to OMA specifications.
![Device Inspector Details](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-details.png)

Device State for CoAP

#### State Auto-Refresh An auto-refresh toggle is located next to the State section title. When enabled, the device telemetry (shadow state) data refreshes automatically every 30 seconds. **When auto-refresh is active:** - The device telemetry data refreshes every 30 seconds - An informative message is displayed indicating that data refreshes every 30 seconds - The 30-second countdown starts after the previous refresh request completes ![state auto-refresh on](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-state-auto-refresh-on.png) **When auto-refresh is disabled:** - The periodic refresh stops immediately **Automatic deactivation:** - If an API error occurs during a refresh cycle, the auto-refresh toggle is automatically turned off - When you navigate away from the State tab to another Device Inspector tab, auto-refresh stops automatically The auto-refresh toggle is available on all protocol sub-tabs (UDP, CoAP, LwM2M) and remains visible even when no messages exist for the selected protocol. ![state auto-refresh off](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-state-auto-refresh-off.png) ### History Whenever messages (UDP, CoAP or LwM2M) from a device are sent to the 1NCE OS endpoint(s) those are stored for 7 days. * UDP or CoAP . Traversed messages are stored. The message format depends on the energy saver status for the specific protocol. If the [Energy Saver](/docs/1nce-os/1nce-os-energy-saver/) is not enabled, then message will be converted and stored in Base64 format, but when enabled, then a processed message will be stored in JSON format. * LwM2M. Messages are stored in JSON format. More details in [Historian Web Interface](/docs/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface) or [Historian API Examples](/docs/1nce-os/1nce-os-device-inspector/device-inspector-historian-api). ### Map If the device is utilizing [Device Locator](/docs/1nce-os/1nce-os-device-locator/), then a location will be pinpointed on a map.
![Device Inspector Details. Map](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-map.png)
*Device location on map* ### Cell Tower Events Cell tower events show the history of cell tower-based location resolutions for selected device when Cell Tower Location is enabled.
![Device Cell Tower Events](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-cell-tower-events.png)
## Limitations * We only show history of the device from the last 7 days, but device state is stored permanently. * History of device is not supporting messages bigger than 2048 bytes. If messages are stored in Base64 [format](/docs/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations#history), then raw binary message size shouldn't exceed 1536 bytes. * Maximum state size for each protocol (UDP, CoAP and LwM2M) is 8192 bytes. * A summary of the location of the device is shown, containing the first position, the last position and some positions inbetween (more data available via the API). * The current digital state representation of a SIM device can be updated **up to 20 times per second**. Therefore, if a given device sends messages at a higher frequency, it would cause a throttling issue resulting in the state not being updated. That is noticeable by the existence of **[DeviceShadowUpdaterThrottlingIssue]** logs in the 1NCE OS Portal Administrator Logs page. * A different issue can happen if a device sends multiple messages in a short interval. That would result in a digital state version conflict and only one of the states will be actually persisted. The existence of **[DeviceShadowUpdaterOnConflict]** represents that situation. * When auto-refresh is active in the History tab, the chart/statistics section is hidden from view. * When auto-refresh is active in the History tab, pagination is disabled — only the latest messages are shown. * The auto-refresh interval is fixed at 30 seconds and is not user-configurable. * Auto-refresh is automatically disabled when an API error occurs during a refresh cycle. --- # Historian API Examples Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-inspector/device-inspector-historian-api/ The Device Inspector Historian has an API to allow users to get their data without going to the portal. The full Historian API description is available in the [API Explorer](/api/). *** # Examples ## Get Messages ### Device messages (7 days) Getting all messages for a specific device for 7 days for a device with iccid `123456789012345678` would be: ```shell curl -X GET https://api.1nce.com/management-api/v1/inspect/devices/history?iccid=123456789012345678 ``` We would receive a response like: ```json { "items": [ { "time": "2022-02-21T12:47:30.085", "payload": "{\"battery\":98,\"saturation\":0.55,\"temperature\":11.6}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T12:47:24.278", "payload": "{\"battery\":99,\"saturation\":0.55,\"temperature\":11.5}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T12:47:21.495", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" } ] } ``` In the response, we can see that a device (that has ICCID “123456789012345678“ and if it has a 1NCE sim also deviceId “123456789012345678“), sent 2 UDP and 1 CoAP message. The payload in each UDP message is a JSON string because the Translation service was used. CoAP message has base64 encoded payload. These are the only messages the device was sending in 7 days because we didn’t specify time constraints and the query was using the default value. ### Messages Timerange Getting messages in the specified time range for the same device but in the time range between `2022-02-21T13:20:00.000` and `2022-02-21T13:22:00.000`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?startDateTime=2022-02-21T13:20:00.000&endDateTime=2022-02-21T13:22:00.000" ``` The response would be in a similar format as before, but the messages would only be those that were received in the requested time range: ```json { "items": [ { "time": "2022-02-21T13:21:50.268", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:41.504", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` Both of the query parameters are optional. If only `startDateTime` is provided, the query will consider the end date-time to be the current time. If only `endDateTime` is provided, the start date-time will be the time 7 days ago. ### Specifying Message Protocol The API can return messages that were sent by the device using a specific protocol (either UDP, CoAP, or LwM2M). To get only CoAP messages sent by the same device `123456789012345678` (without specific time range): ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?protocol=CoAP" ``` We would receive only messages that were sent with CoAP protocol in the last 7 days: ```json { "items": [ { "time": "2022-02-21T13:00:08.066", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" }, { "time": "2022-02-21T13:00:08.056", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" } ] } ``` ### Working with Pagination By default, up to 10 messages are returned from the API. The user is able to specify page size with a query parameter pageSize. The value of this parameter should be between 1 and 25. Example call to get UDP messages of the example device in the page of 3: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history?iccid=123456789012345678&protocol=UDP&pageSize=3" ``` The response would be: ```json { "items": [ { "time": "2022-02-21T13:21:50.268", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:45.480", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:44.360", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ], "nextToken": "AYAFeEdvNYWYGIwsjZX2PFMhRfoAAAA...", "firstToken": "AYAXeFiqDUzhDQ7Tvjydy4JkuuoAAAA..." } ``` We can see that there are two extra fields in the response: nextToken and firstToken. This means that there are more records to see than this. If we would pass nextToken as a query parameter, we would get the next page of data: ```shell curl -X GET "https://api.1nce.com/management-api/v1/devices/messages?iccid=123456789012345678&protocol=UDP&pageSize=3&nextToken=AYAFeEdvNYWYGIwsjZX2PFMhRfoAAAA..." ``` We would get the data: ```json { "items": [ { "time": "2022-02-21T12:47:21.495", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` In this case, there are no extra fields which means no more records to see. If we would provide `firstToken` as a `nextToken` in the query, we would get the same result as we had when we called it the first time (even if there were new messages by this time). ### Specifying Timezone For ease of dealing with time zones, we can specify them in the query. To query in scope of +2 time zone: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?startDateTime=2022-02-21T16:20:00.000+02:00&endDateTime=2022-02-21T16:30:00.000+02:00" ``` We would get the same time zone in the response as well: ```json { "items": [ { "time": "2022-02-21T16:25:57.740", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T16:21:49.651", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` ### Calling endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history" ``` We would get the last 10 messages from all devices within the last 7 days. ```json { "items": [ { "time": "2022-02-21T16:25:57.740", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T17:25:57.740", "payload": "{\"battery\":97,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T18:25:57.740", "payload": "{\"battery\":96,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T19:25:57.740", "payload": "{\"battery\":94,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-22T16:21:49.651", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:23:49.651", "payload": "{\"battery\":98,\"saturation\":0.58,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:25:49.651", "payload": "{\"battery\":98,\"saturation\":0.59,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:27:49.651", "payload": "{\"battery\":98,\"saturation\":0.60,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:29:49.651", "payload": "{\"battery\":98,\"saturation\":0.61,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:31:49.651", "payload": "{\"battery\":98,\"saturation\":0.63,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ], "nextToken": "AYABeJNbCVkFnuUD8Lwc.....", "firstToken": "AYABeGNSdMbKy3uSXn2Z...." } ``` ## Get Historian Insights ### Calling Historian Insights endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history/insights" ``` We would get a number of messages in the 1-day intervals for specific protocols for the last 7 days. ```json { "items": [ { "time": "2022-03-23T00:00:00.000", "protocol": "COAP", "amount": 1 }, { "time": "2022-03-22T00:00:00.000", "protocol": "COAP", "amount": 13 }, { "time": "2022-03-22T00:00:00.000", "protocol": "LWM2M", "amount": 27 }, { "time": "2022-03-21T00:00:00.000", "protocol": "LWM2M", "amount": 1 }, { "time": "2022-03-21T00:00:00.000", "protocol": "UDP", "amount": 1 }, { "time": "2022-03-18T00:00:00.000", "protocol": "LWM2M", "amount": 62 }, { "time": "2022-03-18T00:00:00.000", "protocol": "UDP", "amount": 1 }, { "time": "2022-03-17T00:00:00.000", "protocol": "LWM2M", "amount": 2 } ], "interval": "1d" } ``` --- # Historian Web Interface Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/ To see the Data Historian in the [1NCE OS](https://portal.1nce.com/portal/customer/1nceos), open the Device Inspector and select a device. The device History is presented like this chart: ![daily device history](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_1_day.png) On the horizontal axis, we can see the dates or hours, depending on if we selected the last day or the last 7 days. On the vertical axis, there is the total message amount per day/hour. The bars are split into multiple colored sections. Each section represents message count by a specific source protocol (UDP, CoAP, or LwM2M). The user can toggle protocols shown by clicking on the protocol labels under the chart. In the picture above, we have the last 1 day selected. At 11 AM, there were 4 CoAP messages and 4 LwM2M messages sent by this device. To see the message payload details, click on the colored bar of the required protocol. The latest LwM2M message sent by the device at 5:09:32 PM is shown, and its payload is visible and can be quickly copied by clicking the copy button. We can cycle through the individual payloads by clicking the “Previous” and “Next” buttons.\ By default, the portal tries to convert Base64 messages to JSON format. If the received content is not valid JSON, the portal will display the original message as Base64. If the user has enabled the **energy saver** feature with a valid template for transforming payload into JSON, the portal will display message as a JSON and, if the message is not tranformable with the existing **energy saver** template, there will be an admin log created with the error message. As mentioned, we can see the messages statistics of the last 7 days as well when we change the period selector above the chart: ![weekly device history](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_7_days.png) ## Refreshing Data The History tab provides controls to refresh message data without reloading the entire page. You can trigger a one-time refresh or enable automatic periodic refresh. ### Manual Refresh Button The History tab displays a refresh button in the messages/payload section header. Clicking it refreshes only the messages and payload data shown below the button — the chart statistics above are not re-fetched. This is useful when you want to check for new messages without affecting the chart view or your current filter selections. ![manual history refresh](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_manual_refresh.png) ### Auto-Refresh Toggle An auto-refresh toggle is located in the messages section header of the History tab. When enabled, the messages section refreshes automatically every 30 seconds, providing near-real-time monitoring of incoming device messages. **When auto-refresh is active:** - The chart/statistics section is hidden from view - The pagination buttons (Previous/Next) are disabled - An informative message is displayed explaining that data refreshes every 30 seconds, navigation buttons are disabled, and the latest message is always shown regardless of previous filter or graph selections - The 30-second countdown starts after the previous refresh request completes (not on a fixed wall-clock schedule), so the actual interval between refreshes is 30 seconds plus the request duration - The first automatic refresh occurs 30 seconds after enabling the toggle — the current data is shown immediately ![history auto-refresh](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_auto_refresh.png) **When auto-refresh is disabled:** - The periodic refresh stops immediately - The chart section reappears - Pagination buttons become active again **Automatic deactivation:** - If an API error occurs during a refresh cycle, the auto-refresh toggle is automatically turned off - When you navigate away from the History tab to another Device Inspector tab, auto-refresh stops automatically The auto-refresh toggle is visible even when the messages section has no data (empty state), so you can enable it before messages arrive. --- # Device Integrator Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-integrator/
![Device Integrator as part of the IoT Integrator](/img/1nce-os/1nce-os-device-integrator/IoT-Integrator.png)
The Device Integrator supports connecting devices to 1NCE OS managed services. For that we offer multiple protocols that can be used and tested in the 1NCE OS: UDP, CoAP and LwM2M. The available devices can be found in the [Device Inspector](/docs/1nce-os/1nce-os-device-inspector/). To establish connection we provide special domain names for each protocol. Each domain name resolves to two IP addresses. Those IPs can also be cached on the embedded device if necessary, but we do not guarantee that those IPs will always stay the same. So it is suggested to always have fallback DNS resolvement implemented at some point or at least when connection error occurs. The supported protocols are UDP, CoAP and LwM2M and the connection info is visible in the 1NCE OS frontend. Further information about these protocols can be found in the subpages and the LwM2M chapter: * [UDP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-udp) * [CoAP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap) * [LwM2M](/docs/1nce-os/1nce-os-lwm2m/) **Note:** To successfully reach 1NCE OS endpoints, ensure that the account is configured with the appropriate allowed Breakout network settings, which currently include Europe (Frankfurt) and US East (N. Virginia). For more details, see [Internet Breakout](/docs/network-services/network-services-internet-breakout) --- # CoAP Code Examples Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/ # CoAP Code Examples This page provides runnable Node.js code examples for testing the 1NCE OS CoAP endpoints. All examples use the [`node-coap-client`](https://www.npmjs.com/package/node-coap-client) library version 1.0.9. ## Prerequisites Install the dependency: ```bash npm install node-coap-client@1.0.9 ``` :::tip On environments where native compilation fails (e.g., Termux/Android), you can install with `--ignore-scripts` since the native crypto module is not used on Node.js >= 10. ::: ## Sending CoAP Messages (POST) The following script demonstrates sending telemetry data via CoAP POST, with optional DTLS encryption. ```javascript const coap = require("node-coap-client").CoapClient; /////// Here you can define if you want to enable or disable DTLS requests /////// const dtlsEnabled = true; // (optional) Enable/Disable DTLS ////////////////////////////////////////////////////////////////////////////////// async function coapOnboard(url) { await tryToConnectToCoapServer(url); const options = { keepAlive: true, // Whether to keep the socket connection alive. Speeds up subsequent requests confirmable: true, // Whether we expect a confirmation of the request retransmit: false, // Whether this message will be retransmitted on loss }; console.log(`Calling CoAP bootstrap endpoint ${url}`); const result = await coap.request(url, "get", options); const payload = result.payload?.toString(); if(result.code.toString() !== "2.05") { throw new Error(`Error calling CoAP bootstrap endpoint. Result code: ${result.code.toString()}, Payload: ${payload}`); } console.log(`Boostrap payload: ${payload}`); const [clientIdentity, preSharedKey, coapsEndpointUrl] = payload.split(","); console.log("==================================="); console.log("DTLS details:"); console.log(`Client Identity: ${clientIdentity}`); console.log(`Pre-shared key: ${preSharedKey}`); console.log(`Coap endpoint: ${coapsEndpointUrl}`); console.log("==================================="); return { preSharedKey, clientIdentity, coapsEndpointUrl }; } function logResponseDetails(res) { console.log("========================================================="); console.log("Server Response"); console.log("Status: " + res.code); console.log("Payload: " + res.payload.toString()); console.log("========================================================="); } function enableDtls(url, clientIdentity, preSharedKey) { coap.setSecurityParams(url, { psk: { [clientIdentity]: preSharedKey, }, }); } async function tryToConnectToCoapServer(url) { console.log("Trying to connect to CoAP server"); const res = await coap.tryToConnect(url); if (!res) { console.error("Connection failed to CoAP server"); throw Error(`Failed to connect to coap server: ${url}`); } console.log("Successfully connected to CoAP server"); } async function sendCoapMessage(url, message) { const payload = Buffer.from(message); const options = { keepAlive: true, // Whether to keep the socket connection alive. Speeds up subsequent requests confirmable: true, // Whether we expect a confirmation of the request retransmit: false, // Whether this message will be retransmitted on loss }; console.log(`Sending CoAP message to ${url}`) const result = await coap.request( url, // Server url (string) "post", // Request methos ("get" | "post" | "put" | "delete") payload, // Request payload (buffer) options, // Request options ); logResponseDetails(result); const resultPayload = result.payload?.toString(); if (result.code.toString() !== "2.04") { throw new Error(`Error message received from CoAP server. Result code: ${result.code.toString()}, Payload: ${resultPayload}`); } return { code: result.code.toString(), message: resultPayload, }; } async function callPost(host, topic, message) { try { const protocol = dtlsEnabled ? "coaps" : "coap"; const port = dtlsEnabled ? 5684 : 5683; const url = `${protocol}://${host}:${port}/?t=${topic}`; if (dtlsEnabled) { console.log("Enabling DTLS..."); const boostrapUrl = `coap://${host}:5683/bootstrap`; const { clientIdentity, preSharedKey } = await coapOnboard(boostrapUrl); enableDtls(url, clientIdentity, preSharedKey); console.log("DTLS enabled"); } await tryToConnectToCoapServer(url); await sendCoapMessage(url, message); console.log("Coap message sent"); } catch (error) { console.error("Coap exception", error); throw error; } finally { coap.reset(); } } (async () => { const message = { timestamp: new Date().getTime(), description: "Example message", }; const host = "coap.os.1nce.com"; const topic = "sometesttopic" await callPost(host, topic, JSON.stringify(message)); })(); ``` Enable or disable the CoAP DTLS connection on line 4. By default, the script uses DTLS. ## Retrieving Device Location (GET) The following script retrieves the device location via a CoAP GET request to `/location`. ### Plain CoAP ```javascript const { CoapClient } = require("node-coap-client"); async function getLocation() { try { const url = "coap://coap.os.1nce.com:5683/location"; const options = { keepAlive: false, confirmable: true, retransmit: true, }; console.log(`Requesting location from ${url}`); const result = await CoapClient.request(url, "get", undefined, options); const code = result.code.toString(); if (code === "4.01") { console.error("Unauthorized: Device not found by source IP"); return; } if (code === "4.04") { console.error("Not Found: No location data available for this device"); return; } if (code === "4.05") { console.error("Method Not Allowed: Only GET requests are supported on /location"); return; } if (code === "5.02") { console.error("Bad Gateway: Upstream location service error"); return; } if (code === "5.04") { console.error("Gateway Timeout: Upstream location service did not respond"); return; } if (code !== "2.05") { console.error(`Unexpected response code: ${code}`); return; } const payload = result.payload.toString(); console.log(`Response payload:\n${payload}`); // Parse CSV: split on line-feed to get rows, then split data row on comma const rows = payload.split("\n"); const dataRow = rows[1]; const [Longitude, Latitude, Source, SampleTime] = dataRow.split(","); console.log("==================================="); console.log("Device Location:"); console.log(`Longitude: ${Longitude}`); console.log(`Latitude: ${Latitude}`); console.log(`Source: ${Source}`); console.log(`SampleTime: ${SampleTime}`); console.log("==================================="); } catch (error) { console.error("CoAP exception", error); throw error; } finally { CoapClient.reset(); } } (async () => { await getLocation(); })(); ``` ### DTLS Variant This variant first calls `/bootstrap` to obtain PSK credentials, then accesses the location endpoint securely. ```javascript const { CoapClient } = require("node-coap-client"); async function getLocationWithDtls() { try { const host = "coap.os.1nce.com"; // Step 1: Call /bootstrap to obtain PSK credentials const bootstrapUrl = `coap://${host}:5683/bootstrap`; console.log(`Calling CoAP bootstrap endpoint ${bootstrapUrl}`); const bootstrapResult = await CoapClient.request(bootstrapUrl, "get", undefined, { keepAlive: false, confirmable: true, retransmit: true, }); if (bootstrapResult.code.toString() !== "2.05") { throw new Error(`Bootstrap failed. Code: ${bootstrapResult.code.toString()}`); } const bootstrapPayload = bootstrapResult.payload.toString(); const [clientIdentity, preSharedKey] = bootstrapPayload.split(","); console.log("==================================="); console.log("DTLS details:"); console.log(`Client Identity: ${clientIdentity}`); console.log(`Pre-shared key: ${preSharedKey}`); console.log("==================================="); // Step 2: Set DTLS security params and request location const locationUrl = `coaps://${host}:5684/location`; CoapClient.setSecurityParams(locationUrl, { psk: { [clientIdentity]: preSharedKey, }, }); const options = { keepAlive: false, confirmable: true, retransmit: true, }; console.log(`Requesting location from ${locationUrl}`); const result = await CoapClient.request(locationUrl, "get", undefined, options); const code = result.code.toString(); if (code === "4.01") { console.error("Unauthorized: Device not found by source IP"); return; } if (code === "4.04") { console.error("Not Found: No location data available for this device"); return; } if (code === "4.05") { console.error("Method Not Allowed: Only GET requests are supported on /location"); return; } if (code === "5.02") { console.error("Bad Gateway: Upstream location service error"); return; } if (code === "5.04") { console.error("Gateway Timeout: Upstream location service did not respond"); return; } if (code !== "2.05") { console.error(`Unexpected response code: ${code}`); return; } const payload = result.payload.toString(); console.log(`Response payload:\n${payload}`); // Parse CSV: split on line-feed to get rows, then split data row on comma const rows = payload.split("\n"); const dataRow = rows[1]; const [Longitude, Latitude, Source, SampleTime] = dataRow.split(","); console.log("==================================="); console.log("Device Location:"); console.log(`Longitude: ${Longitude}`); console.log(`Latitude: ${Latitude}`); console.log(`Source: ${Source}`); console.log(`SampleTime: ${SampleTime}`); console.log("==================================="); } catch (error) { console.error("CoAP exception", error); throw error; } finally { CoapClient.reset(); } } (async () => { await getLocationWithDtls(); })(); ``` --- # CoAP Endpoint Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap/ ## CoAP Overview The CoAP Endpoint `coap://coap.os.1nce.com:5683` hosts a POST endpoint on the server root path (`/`) or on the `/data` path if device firmware for some reason cannot send to the root path. The endpoint supports both normal, non-translatable messages and translatable messages by using the Energy Saver, with a safe payload size of up to 1024 bytes. The POST endpoint takes an optional query parameter (or Location-Query) `t` to provide the MQTT topic used for forwarding this message to an MQTT broker (e.g., `coap://coap-service:5683/?t=topicName` or `coap://coap-service:5683/data?t=topicName`). The Location-Query is limited to 255 characters by the CoAP protocol, hence the topic name itself can only contain up to 253 characters (`t` and `=` also count as characters). The topic name can only contain alphanumeric characters, underscores, and forward slashes (no two slashes in a row). If these constraints are violated, a Bad Request (4.00) will be returned. If a targeted device could not be found or is in a non-active status, the CoAP service will return an Unauthorized (4.01) response and no further processing of the message will take place. ## CoAP Communication While using UDP protocol for transport, the CoAP protocol offers reliable communication by using a message confirmation mechanism. Each CoAP request has to be acknowledged by the server, so that the client can be sure that the message was processed:
![CoAP reliable messaging](/img/1nce-os/1nce-os-device-integrator/device-integrator-coap/coap-con.png)
There are a few key moments that allow reliable communication: 1. To maximize the chance that the message succeeds even in a lossy network environment, CoAP has a retransmission mechanism. The client re-sends the Confirmable message (`CON`) until the Acknowledgement (`ACK`) is received or the *exchange lifetime* has ended. The total exchange lifetime (`EXCHANGE_LIFETIME`) is the time from starting to send a Confirmable message to the time when an acknowledgment is no longer expected.\ By default, the `EXCHANGE_LIFETIME` value is `247 seconds`. 2. CoAP messages contain a *Message ID* (also known as `MID`) to detect duplicates due to retransmissions. The Message ID has to be unique during the `EXCHANGE_LIFETIME`, so the client's endpoint should be able to specify a unique `MID` value if messages are being sent often enough. Most high-level CoAP clients manage `MID` uniqueness internally, but for low-level clients like the *Quectel BG95* modem, it can be specified in the AT command as `msgID`: ```text AT+QCOAPHEADER=,,[,,] ``` There are two examples of the retransmission situation in a single exchange lifetime: * The client's `CON` message did not reach the server. The client resends the same `CON` message with the same `MID`. * The server's `ACK` message did not reach the client. The client resends the same `CON` message with the same `MID` (because there was no acknowledgment). The server responds with the same `ACK` because it sees the already-processed `MID` and does not process the request again. ## DTLS Encryption for CoAP
![CoAP DTLS Support](/img/1nce-os/1nce-os-device-integrator/device-integrator-coap/coap-onboarding.png)
Ensuring data is securely sent from a device to 1NCE OS is an important part of gaining customer trust. To provide this secure connection, 1NCE OS has implemented a DTLS layer in the CoAP communication from the device to 1NCE OS. This allows the device to securely send its data without the possibility of messages being read or modified along the way. The diagram above describes this process. First, when the device is ready to onboard itself, it calls the CoAP bootstrapping endpoint. This retrieves the necessary DTLS credentials to onboard securely and initialize the CoAP connection using a PSK. To utilize DTLS encryption with 1NCE OS, a pre-shared key (PSK) is essential for securing data. This key encrypts and decrypts transmitted data. Devices can connect securely using CoAP with DTLS by accessing the endpoint `coaps://coap.os.1nce.com:5684` or `coaps://coap.os.1nce.com:5684/data`. To retrieve the PSK, send a GET request to `coap://coap.os.1nce.com:5683/bootstrap`. This endpoint will return an existing key, or if none is available, it will generate and provide a new one. Additionally, you can manually set the PSK (in plaintext or HEX format): * Through the 1NCE OS API endpoint described in [API Explorer](/api/1nce-os/create-pre-shared-device-key/). * In the 1NCE OS portal Device Integrator when [testing the CoAP endpoint](/docs/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints#testing-the-endpoint). ### DTLS Bootstrapping Information The pre-shared key is valid indefinitely. If the bootstrapping is called 5 or more minutes after the last time bootstrapping was called and the pre-shared key was not set previously by the user, the pre-shared key will be regenerated with a new value. | Name | Type | Description | | :------------- | :----- | :------------------------------------------------------------------ | | clientIdentity | string | The ICCID of the device SIM | | preSharedKey | string | A pre-shared key the device can use to authenticate itself on DTLS | | coapsEndpointUrl | string | The CoAPS endpoint URL for DTLS-encrypted communication | **Example response:** ```text 8988280666000000000,aB3dEf7hIjKlMnOp,coaps://coap.os.1nce.com:5684 ``` For a complete runnable example of sending CoAP messages (with optional DTLS), see the [CoAP Code Examples](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/#sending-coap-messages-post) page. ## Location Endpoint The Location Endpoint at path `/location` allows IoT devices to retrieve their last known geographic position. The device is identified using the [SIM-as-an-Identity](/docs/1nce-os/1nce-os-device-authenticator/#sim-as-an-identity) principle and supports only the GET method. Non-GET requests receive a CoAP 4.05 (Method Not Allowed) response. The endpoint is accessible via: - Plain CoAP: `coap://coap.os.1nce.com:5683/location` - DTLS-encrypted CoAPS: `coaps://coap.os.1nce.com:5684/location` ### Response Format A successful request returns a CoAP 2.05 (Content) response with Content-Format set to text/plain. The response body is formatted as CSV with a comma (`,`) delimiter and line-feed (`\n`) line ending. The first row is a header line with column names. **Response information model:** | Name | Type | Description | | :--- | :--- | :---------- | | Longitude | string (decimal degree numeric) | Geographic longitude of the device | | Latitude | string (decimal degree numeric) | Geographic latitude of the device | | Source | string | Identifier of the location source (e.g., [GPS](/docs/1nce-os/1nce-os-device-locator/#gps-location), [CellTower](/docs/1nce-os/1nce-os-device-locator/#cell-tower-location)) | | SampleTime | string (integer EPOCH seconds) | Timestamp of the location measurement in seconds since 1970-01-01 UTC | **Example response:** ```text Longitude,Latitude,Source,SampleTime 13.404954,52.520008,GPS,1700000000 ``` ### Authentication The device is authenticated by source IP address lookup. The CoAP server resolves the device identity from the requesting IP address. Devices can access the Location Endpoint via plain CoAP (`coap://coap.os.1nce.com:5683/location`) or securely via DTLS-encrypted CoAPS (`coaps://coap.os.1nce.com:5684/location`) using a PSK obtained from the `/bootstrap` endpoint. For details on obtaining PSK credentials for DTLS encryption, see the [DTLS Encryption for CoAP](#dtls-encryption-for-coap) section. If the source IP address does not match any registered device, the endpoint returns CoAP 4.01 (Unauthorized). ### Response Codes The following table lists all response codes returned by the Location Endpoint: | Code | Description | Payload | | :--- | :---------- | :------ | | 2.05 | Content — Successful response with CSV location data | CSV location data | | 4.00 | Bad Request — Invalid request | Empty | | 4.01 | Unauthorized — Device not recognized | Empty | | 4.03 | Forbidden — Access denied | Empty | | 4.04 | Not Found — No location data available for the device | Empty | | 4.05 | Method Not Allowed — Non-GET request sent to the endpoint | Empty | | 5.02 | Bad Gateway — Service temporarily unavailable | Empty | | 5.04 | Gateway Timeout — Service did not respond in time | Empty | All error responses (4.xx and 5.xx) return an empty payload. For runnable examples of retrieving device location (plain CoAP and DTLS), see the [CoAP Code Examples](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/#retrieving-device-location-get) page. ## CoAP Endpoint Information Base URL: `coap.os.1nce.com`\ Protocol: CoAP(s)\ Supported Paths: - `/` or `/data` — for telemetry data - `/bootstrap` — for DTLS bootstrapping - `/location` — for device location retrieval (GET only) ### Response Codes | Code | Description | Payload | | :--- | :---------- | :------ | | 2.04 | Changed — Telemetry data accepted (`/` and `/data`) | Empty | | 2.05 | Content — Successful response | `/bootstrap`: CSV with clientIdentity, preSharedKey, coapsEndpointUrl; `/location`: CSV with Longitude, Latitude, Source, SampleTime | | 4.00 | Bad Request — Invalid request | Empty | | 4.01 | Unauthorized — Device not recognized | Empty | | 4.03 | Forbidden — Access denied | Empty | | 4.04 | Not Found — No data available for the device | Empty | | 4.05 | Method Not Allowed — Unsupported method for the path | Empty | | 5.00 | Internal Server Error | Empty | | 5.02 | Bad Gateway — Service temporarily unavailable | Empty | | 5.04 | Gateway Timeout — Service did not respond in time | Empty | ## Features & Limitations ### Features - Reliable messaging via CoAP confirmable messages with retransmission - DTLS encryption for secure data transport using pre-shared keys - Telemetry data forwarding to MQTT brokers via topic query parameter - Device location retrieval via GET `/location` (plain CoAP and DTLS) - Automatic device authentication via [SIM-as-an-Identity](/docs/1nce-os/1nce-os-device-authenticator/#sim-as-an-identity) ### Limitations The main limitation of DTLS is the use of the UDP protocol. The major drawbacks of using UDP are having to deal with packet reordering, loss of datagrams, and data larger than the size of a datagram network packet. --- # Test Endpoints Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/ ## Testing the endpoint It is possible to test the integration directly in the 1NCE portal. To do so, data should be sent to the desired endpoint: 1. _Test Integration_ should be selected for the desired protocol. 2. Device ID (ICCID) should be provided, from which the data is expected. 3. If required for CoAP & LwM2M, DTLS Pre-Shared Key can be configured in HEX or Plain-text format. 4. After clicking _Test Integration_, portal will wait for data to arrive from the device. 5. If data was sent successfully, a message will be displayed in JSON form for LwM2M messages, or if [Energy Saver Template](/docs/1nce-os/1nce-os-energy-saver/) is being used for CoAP, UDP. The message will be displayed in base64 format if Energy saver is not being used.
![Test Integration Form for CoAP](/img/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/test-integration.png)
![Message received](/img/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/device-integrator-message-received.png)
### Troubleshooting Troubleshooting might be required if testing the endpoint fails (i.e., the message is not received). #### Breakout Region 1NCE OS is currently only available through the Europe (Frankfurt) and US East (N. Virginia) breakout regions. Please validate that the correct region is selected under Configuration. If the wrong breakout region was being used, select the correct region, and the device should create a new PDP context. A simple way to achieve this is by rebooting the device. #### Energy Saver If an invalid [Energy Saver Template](/docs/1nce-os/1nce-os-energy-saver/) is enabled, data will not be processed. Please validate that no errors are found in the [Admin Logs](/docs/1nce-os/1nce-os-admin-logs/) related to the Energy Saver. If errors from the Energy Saver are found in the Admin Logs, please disable the Energy Saver Template for the protocol and try again. --- # UDP Endpoint Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-integrator/device-integrator-udp/ The UDP Endpoint receives packets sent by the customer's IoT devices with a maximum safe payload size of 508 bytes, enriches them with identifier data from the core network and forwards data to the customer's configured backend application via the Data Broker. The following address has to be used to send UDP Messages `udp://udp.os.1nce.com:4445`. A simple script to send UDP packets to the server will look like this (generic example in NodeJS): ```javascript const dgram = require('dgram'); const message = Buffer.from('Hello World'); const client = dgram.createSocket('udp4'); client.send(message, 4445, 'udp.os.1nce.com', (err) => { if (err) console.err(err); client.close(); return 'done'; }); ``` All active SIMs from an organization will be able to successfully publish messages via the UDP Endpoint, if [Terms of Use](https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf) & [Data Processing Agreement](https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf) are accepted. The incoming messages can be found in [historian web interface](/docs/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/). All TELEMETRY\_DATA events which are forwarded to the AWS IoT Core are sent to a device-specific topic with the following format for UDP and LwM2M:\ **\{iccid}/messages** For CoAP:\ **\{iccid}/\{coap\_topic}** or **\{iccid}** if no topic provided (see optional query parameter in [CoAP overview](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap)) This will result in a nicely formatted JSON-message that is also human-readable: ## Example Implementation for UDP Endpoint The following example uses Python 3.8: ```python import socket import logging import sys def send_udp_message(host, port, message): logging.basicConfig(level=logging.INFO, stream=sys.stdout, format='%(asctime)s %(levelname)s: %(message)s') logger = logging.getLogger(__name__) logger.info("Opening UDP Socket") udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) try: logger.info("Sending UDP message to {}:{} with body {}".format(host,port,message)) udp_socket.sendto(message.encode(), (host, port)) logger.info("Sent UDP Message to the UDP Broker") except Exception as e: logger.error("Error sending UDP message:", e) finally: udp_socket.close() send_udp_message("udp.os.1nce.com", 4445, "Hello, UDP. Can you hear me?") ``` UDP is the most lightweight transport protocol and can easily be based on a simple socket connection as shown in the previous example. --- # Device Locator Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/
![](/img/1nce-os/1nce-os-device-locator/device-locator.png)
## Overview 1NCE OS provides the ability to manage and view device positions using both the API and the frontend. An interactive map showing all customer devices is available on the Device Locator page, and the location history of individual devices over the last 7 days can be accessed on the Device Inspector page. 1NCE OS utilizes and processes multiple sources of device location data: * GPS data via the Energy Saver template. * GPS data via LwM2M using the /6/0/0 object. * Cell tower location data using SIM network tower connections. ## Cell Tower Location The Device Locator provides an approximate position of IoT devices by analyzing data from network events when creating a new PDP Context/Session used for data transmission. This feature has to be activated in the portal. To view latest particular device cellTower location resolution attempts [Activity endpoint](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity) can be used.
![Enabling the Cell Tower location feature](/img/1nce-os/1nce-os-device-locator/enabling-cell-tower-location.png)
:::info Terminology The Cell Tower Location feature offers two solver modes: - **Basic** — included by default at no extra cost. Resolves locations using open cell tower databases. - **Plus** — a paid upgrade requiring [Device Location Credits](#device-location-credits). Provides higher accuracy and broader coverage for 3G, 4G, and LTE-M. When Plus is enabled, it can operate in two configurations: - **DEFAULT** — all devices share the same resolution frequency (once per hour). - **CUSTOM** — per-device resolver and frequency control (60–1440 minutes), managed via the API or the Plus Resolution tab in the portal. See [Per-device configuration (CUSTOM mode)](#per-device-configuration-custom-mode). DEFAULT and CUSTOM are modes within the Plus solver — they do not apply to Basic mode. ::: ### Basic mode By default, the Basic solver mode is enabled, which delivers device positioning when connected via 2G technology. Resolved position is based on the location of the cell tower device is connected to. Positioning for 3G, 4G, LTE-M, and NB-IoT connections is not guaranteed and may not be resolved. Creative Commons License OpenCelliD Project is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License ![](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) ### Plus mode When Plus solver mode is enabled, it improves the Cell Tower Location accuracy and coverage particularly for 3G, 4G and LTE-M. However, NB-IoT resolutions will not be performed in Plus solver mode. Up to 95% of all cell tower locations are successfully resolved using the Plus solver mode. New metadata field is also added with accuracy data. In the following example, the circle around the point on the map indicates that there is a 68% probability that the device is within a 270-meter radius of the provided location.
![Enabled Advanced solver mode with credits available](/img/1nce-os/1nce-os-device-locator/plus-mode.png) *Enabled Plus solver mode with credits available*
![Advanced solver mode](/img/1nce-os/1nce-os-device-locator/cell-tower-location.png) *Plus solver mode*
#### Device Location Credits Each cell tower resolution consumes 1 credit from the Device Locator credit balance. The credit balance is refreshed periodically throughout the day. If all credits are depleted or the current date reaches the credit expiry date, the Plus solver mode automatically switches to Basic mode. You can request access to this feature via the 1NCE OS portal. Credits can be purchased via the Orders tab in the 1NCE Portal by choosing the required quantity of "Whereabouts – Device Location" credits. #### Per-device configuration (CUSTOM mode) When Cell tower Plus is first enabled, it runs in DEFAULT mode — cell tower location data is resolved no more frequently than once an hour for all devices in your organization. CUSTOM mode lets you override this by configuring Cell tower Plus on a per-device basis, enabling Plus location resolution only for selected devices with individually configurable frequency intervals (60–1440 minutes). All other devices without a frequency configuration fall back to the Basic resolver. Per-device Plus resolution can also be configured through the Plus Resolution tab in the portal. For a step-by-step guide on switching to CUSTOM mode, enabling and disabling Cell tower Plus for individual devices, and querying per-device settings, see [Per-device Cell tower Plus](/docs/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/). ### Cell Tower Events The Cell tower events tab displays the history of cell tower-based location resolution attempts for a selected device. For the full field reference, the Network Event Resolver walkthrough, usage limits, and restrictions, see [Cell Tower Events](/docs/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/). ## GPS Location ### Via Energy Saver If the Energy Saver with `custom_type` in the JSON-Template is used, the location from the device can be obtained over the Energy Saver output. Visit [Energy Saver](/docs/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration) for more details. ```json { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` ### Via LwM2M If LwM2M is used, the following Resource Addresses can be used to provide the device location: `/6/0/0` (latitude, Float), `/6/0/1` (longitude, Float) and `/6/0/5` (timestamp, Time). Visit our [LwM2M Service Documentation](/docs/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration) for more details on integrating LwM2M with the device locator. ## Geofencing The Geofencing Service allows setting virtual boundaries for devices. If a device is crossing a geofence (entering or exiting, configurable), a [geofence event](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format#geofence) will be generated and sent to the customer's Cloud Integrator Webhook integration or the AWS Integration. To start using Geofencing you need to purchase "Whereabouts - Geofencing" [credits](/docs/1nce-os/1nce-os-device-locator/#geofence-credits) first. You can use following [Get customer settings](/api/1nce-os/get-customer-settings/) API endpoint to check if credits are already assigned to you. Once the credits are available, you can create your first geofence using the [Create Geofence](/api/1nce-os/create-geofence/) API endpoint. For additional info about Geofence creation use following [page](/docs/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/). Main use cases for geofencing are: * Notify user in case if a device or an object this device is attached to exits specific area. * Notify user in case if a device or an object this device is attached to enters specific area. ### Geofence Credits Each location event sourced from cell towers or GPS is evaluated against associated geofences in the 1NCE OS. If at least one geofence is evaluated for a potential breach, then one Geofencing credit is consumed. The Geofencing credit balance is refreshed periodically throughout the day. Additional credits can be purchased via the Orders tab in the 1NCE Portal by selecting the required quantity of "Whereabouts – Geofencing" credits. If all credits are depleted or expired then the Geofencing feature is automatically turned off, which means the following: * you will no longer receive exit or enter [geofence events](/docs/1nce-os/1nce-os-cloud-integrator/#geofence-events) via your Cloud Integration if the device breaches any existing geofence. * you will not be able to create any new Geofences, only update or delete existing ones. * existing Geofences and associated latest device enter or exit events will continue to exist in passive mode until extra credits are purchased.
![Geofence Credits](/img/1nce-os/1nce-os-device-locator/geofencing-credits.png) *Geofence Credits*
## Disclaimer I acknowledge that activating the location feature involves processing nearby Cell Tower data by 1NCE. 1NCE processing of data is done anonymously. I understand that if the use of the service by me makes it linkable to individuals, additional data related responsibilities may apply. As per [1NCE General Terms and Conditions (GTC)](https://1nce.com/wp-content/1NCE-business-terms-EN.pdf), I am solely responsible for complying with Data Protection laws and regulations and obtaining necessary consents. --- # Per-device Cell tower Plus Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/ ## Prerequisites - **Authentication** — Bearer token required. See [authorization flow](/api/authorization/authorization/). - **Device Location Credits** — Active [Device Location Credits](/docs/1nce-os/1nce-os-device-locator/#device-location-credits) must be available in your account. - **API rate limits** — Review the [rate limits](/api/api-rate-limits/) to avoid throttling. ## Understanding Cell tower Plus Modes :::info Terminology **Basic** and **Plus** are the two solver modes for Cell Tower Location. Basic is free. Plus is a paid upgrade (requires [Device Location Credits](/docs/1nce-os/1nce-os-device-locator/#device-location-credits)) offering higher accuracy for 3G/4G/LTE-M. The **DEFAULT** and **CUSTOM** configurations described below apply only to the Plus solver mode. ::: The Cell tower Plus setting can be in one of the following states: - **DEFAULT** — Cell tower Plus applies uniformly to all devices — cell tower location data is resolved no more frequently than once an hour. This is the initial mode when the feature is first enabled. - **CUSTOM** — You control which devices have their network events processed with the Plus solver, and how frequently (60–1440 minutes). The frequency determines the minimum interval at which network events from a device are picked up for location resolution. All other devices fall back to basic resolution. | Organization mode | Devices with frequency set | Other devices | |---|---|---| | **DEFAULT** | All devices: Plus resolution once per hour | All devices: Plus resolution once per hour | | **CUSTOM** | Plus resolution at configured frequency | Basic resolution only (once per hour) | | **Disabled (no purchased credits)** | Basic resolution only (once per hour) | Basic resolution only (once per hour) | :::warning When using the API, switching to CUSTOM mode is required before enabling or disabling Cell tower Plus on individual devices. Attempting per-device operations without CUSTOM mode active results in a **403 Forbidden** response. In the portal, the switch to CUSTOM mode happens automatically when you save the first per-device configuration — no manual step is needed. ::: ## Portal — Plus Resolution Tab The Plus Resolution tab is the fourth tab on the Device Locator page. It is always visible in the navigation regardless of the Cell tower Plus setting state. ### Tab States - **Disabled state** — When Cell tower Plus is not enabled or Device Location Credits are exhausted, the tab shows an informative message with a "View documentation" link. The full tab content is not accessible until Cell tower Plus is enabled for the customer. - **Enabled state** — When Cell tower Plus is enabled and credits are available, the tab renders the Mode Dropdown, Manage SIMs section, and Enabled SIMs Table.
![Plus Resolution tab in disabled state](/img/1nce-os/1nce-os-adl-per-device/disabled.png) *Plus Resolution tab — disabled state*
A page-level refresh re-checks the Cell tower Plus setting state. ### Batch Processing and Progress When a batch operation is submitted, the portal divides the selected SIMs into sequential chunks of 100 and processes each chunk one at a time. A progress indicator is displayed during processing. - **Full success** (zero failures) — A success toastr notification is displayed and the Enabled SIMs Table refreshes automatically. - **HTTP error** — A toastr error notification is displayed. - **Partial failure** — The Result Modal opens showing success/failure counts and the list of failed ICCIDs with a download button.
![Result Modal showing success and failure counts with failed ICCIDs](/img/1nce-os/1nce-os-adl-per-device/partial_success.png) *Result Modal — partial failure with downloadable failed ICCID list*
:::info The 100-device chunk size is a fixed system limit. For large CSV uploads, the portal handles chunking automatically. ::: ## Workflow ### Step 1 – Switch to CUSTOM Mode Patch the Cell tower Plus setting with `{"mode": "CUSTOM"}` to enable per-device configuration. **Endpoint:** [`PATCH /v1/settings/1nceos/ADVANCED_CELL_TOWER_LOCATION/details`](/api/1nce-os/patch-setting-details/) [API example](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#switch-to-custom-mode) #### Via the Portal In the Plus Resolution tab, select **"Specific SIMs"** from the "Use Plus resolution for" dropdown. The actual mode transition does not happen when the dropdown is changed — it occurs silently in the background when you save the first per-device configuration via the Manage SIMs section.
![Mode dropdown set to All with informational message in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/All_sims.png) *Plus Resolution tab showing the "Use Plus resolution for" dropdown*
:::warning Switching from "Specific SIMs" (CUSTOM) back to "All" (DEFAULT) is not available through the portal. ::: ### Step 2 – Enable Cell tower Plus for Devices Enable Plus resolution for selected devices by providing their ICCIDs and a frequency value. **Endpoint:** [`POST /v1/locate/devices/settings`](/api/1nce-os/enable-adl-device-location-settings/) [API example](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#enable-cell-tower-plus-for-devices) #### Via the Portal In the Plus Resolution tab, expand the **Manage SIMs** section and select **"Create/Update"** from the Operation dropdown. Choose a SIM selection method: - **Single ICCID** — enter a single 19-digit ICCID - **ICCID Range** — provide start and end ICCIDs (max 100 devices) - **ICCID Ranges CSV** — upload a CSV file (up to 200 KB) with comma- or semicolon-separated ICCIDs Enter the desired frequency (60–1440 minutes) and click **Save**.
![Manage SIMs section with Single ICCID selection and frequency input in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/single_iccid.png) *Create/Update operation with Single ICCID selection*
### Step 3 – Query Per-Device Settings Retrieve which devices have per-device Cell tower Plus enabled. **Endpoint:** [`GET /v1/inspect/devices/settings/DEVICE_ADL`](/api/1nce-os/get-per-device-settings/) [API example](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#get-per-device-settings) #### Via the Portal In the Plus Resolution tab, the **Enabled SIMs Table** displays all devices with per-device Plus resolution enabled. The table shows two columns: Device ID (ICCID) and Frequency. Use the collapsible **Filters** section to filter by ICCID, and the page size dropdown ("Show N SIMs per page") to control how many rows are displayed. The table supports pagination with up to 50 pages.
![Enabled SIMs Table with ICCID filter applied and pagination controls in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/Filtered_table.png) *Enabled SIMs Table with filters and pagination*
### Step 4 – Update Device Frequency Update the resolution frequency for devices that already have Cell tower Plus enabled. Use the same endpoint and method as enabling — submitting an existing ICCID with a new frequency value overwrites the previous configuration. **Endpoint:** [`POST /v1/locate/devices/settings`](/api/1nce-os/enable-adl-device-location-settings/) [API example](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#enable-cell-tower-plus-for-devices) #### Via the Portal There are two ways to update device frequency in the portal: **Bulk update via Manage SIMs section** — In the Plus Resolution tab, expand the **Manage SIMs** section with **"Create/Update"** selected, enter the target ICCIDs using any SIM selection method, provide the new frequency value, and click **Save**. Devices that already have Plus enabled will have their frequency updated to the new value. **Row-level edit from the Enabled SIMs Table** — Click the edit (pencil) icon on any row in the Enabled SIMs Table. The Edit Frequency Modal opens pre-populated with the current value. Enter the new frequency (60–1440 minutes) and confirm.
![Edit Frequency modal with pre-populated frequency value](/img/1nce-os/1nce-os-adl-per-device/edit_frequency.png) *Edit Frequency modal — update the resolution frequency for a single device*
### Step 5 – Disable Cell tower Plus for Devices Disable Plus resolution for selected devices. **Endpoint:** [`DELETE /v1/locate/devices/settings`](/api/1nce-os/disable-adl-device-location-settings/) [API example](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#disable-cell-tower-plus-for-devices) #### Via the Portal There are two ways to disable Plus resolution for devices in the portal: **Bulk delete via Manage SIMs section** — In the Plus Resolution tab, expand the **Manage SIMs** section and select **"Delete"** from the Operation dropdown. Choose a SIM selection method (Single ICCID, ICCID Range, or ICCID Ranges CSV), enter or upload the target ICCIDs, and click **Save**. The frequency input is not shown for delete operations.
![Delete operation in the Manage SIMs section with CSV upload showing parsed ICCID count](/img/1nce-os/1nce-os-adl-per-device/delete_batch.png) *Delete operation with CSV upload showing parsed ICCID count*
**Row-level delete from the Enabled SIMs Table** — Click the trash icon on any row in the Enabled SIMs Table. A confirmation modal asks "Are you sure you want to remove this SIM from Plus resolution?" with **Cancel** and **Remove** buttons.
![Row-level delete confirmation modal asking to remove a SIM from Plus resolution with Cancel and Remove buttons](/img/1nce-os/1nce-os-adl-per-device/delete_table_button.png) *Row-level delete confirmation modal*
## Additional Behavior - **New SIMs** — When a new SIM is activated in CUSTOM mode, it defaults to basic resolution. You must explicitly enable it via the POST endpoint or via the Manage SIMs section in the portal. - **Credits exhausted** — The system falls back to the Basic resolver. Mode and per-device configurations remain intact, and Plus resolution resumes automatically when credits are replenished. Purchase additional credits via the **Orders** tab in the 1NCE Portal ("Whereabouts – Device Location"). - **Credit debt** — Deducted from the next batch of purchased credits. - **Switching back to DEFAULT** — Not available via the API or the portal. When the switch is performed, all per-device frequency configurations are permanently removed. ## Related Resources - [API Examples — Per-device Cell tower Plus](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#per-device-cell-tower-plus) - [Portal — Plus Resolution Tab](#portal--plus-resolution-tab) - [Enable ADL Device Location Settings](/api/1nce-os/enable-adl-device-location-settings/) — API Explorer - [Disable ADL Device Location Settings](/api/1nce-os/disable-adl-device-location-settings/) — API Explorer - [Get Per-Device Settings](/api/1nce-os/get-per-device-settings/) — API Explorer - [Patch Setting Details](/api/1nce-os/patch-setting-details/) — API Explorer - [Device Locator overview](/docs/1nce-os/1nce-os-device-locator/) - [API rate limits](/api/api-rate-limits/) --- # API Examples Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/device-locator-api/ :::info Authentication All Device Locator API endpoints require Bearer token authentication. See [authorization flow](/api/authorization/authorization/) for details on obtaining a token. ::: ## Cell Tower Location ### Get Device Positions Get positions of a specific device for the last 7 days. Get a list of positions for device with id `1234567890123456789`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/devices/1234567890123456789/positions" ``` The response could be `200 OK` with body: ```json { "coordinates": [ { "sampleTime": "2024-05-03T11:00:24.985Z", "coordinate": [ 24.16962242126465, 56.97812271118164 ], "source": "CellTower", "metadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 } }, { "sampleTime": "2024-05-03T02:10:17.798Z", "coordinate": [ 24.16717529296875, 56.97748947143555 ], "source": "CellTower", "metadata": { "verticalAccuracy": 577, "horizontalAccuracy": 300, "verticalConfidenceLevel": 0.68, "horizontalConfidenceLevel": 0.68 } } ], "pageAmount": 1, "page": 1 } ``` :::warning Note that `metadata` parameter with accuracy data is only available in Cell tower **Plus** mode. ::: ### Get Latest Devices Positions Get latest positions of customer devices for the last 7 days. ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/positions/latest" ``` The response could be `200 OK` with body: ```json { "coordinates": [ { "deviceId": "1234567890123456788", "sampleTime": "2024-05-07T15:40:12.703Z", "coordinate": [ 24.164257049560547, 56.974369049072266 ], "source": "GPS" }, { "deviceId": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "coordinate": [ 24.16962242126465, 56.97812271118164 ], "source": "CellTower", "metadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 } } ], "pageAmount": 1, "page": 1 } ``` :::warning Note that `metadata` parameter with accuracy data is only available in Cell tower **Plus** mode. ::: :::warning Note that only one latest position is possible for a single device independent of source: either Celltower or GPS. This means that `source` query parameter selection can lead to no latest position returned for some devices. ::: ### Get Device Activity Get Cell location resolutions for one device (maximum of last 7 days, defaults to 1 day). Both resolved and unresolved location resolution attempts are returned. Get a list of location resolutions for device with id `1234567890123456789` ordered by sampleTime DESC: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/devices/1234567890123456789/activity" ``` The response could be `200 OK` with body: ```json { "items": [ { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "towerMetadata": { "MCC": "247", "MNC": "1", "LAC": "11", "CellID": "9511" }, "towerLocation": { "longitude": 24.16962242126465, "latitude": 56.97812271118164 }, "resolutionMetadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 }, "radioAccessType": "2G", "resolutionMode": "ADVANCED", "locationResolutionStatus": "SUCCEEDED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "towerLocation": { "longitude": 24.16962242126465, "latitude": 56.97812271118164 }, "radioAccessType": "2G", "resolutionMode": "BASIC", "locationResolutionStatus": "SUCCEEDED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T10:00:24.985Z", "towerMetadata": { "MCC": "247", "MNC": "1", "LAC": "11", "CellID": "9511" }, "radioAccessType": "2G", "resolutionMode": "ADVANCED", "locationResolutionStatus": "FAILED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T09:00:24.985Z", "radioAccessType": "2G", "resolutionMode": "BASIC", "locationResolutionStatus": "FAILED" } ] } ``` :::warning Note that `towerMetadata` and `resolutionMetadata` parameters with accuracy data and tower identifier are only available in Cell tower **Plus** mode. ::: :::warning Note that, regardless of the different radio access technology types, the `LAC` property in the `towerMetadata` object can represent `TAC`. ::: ![](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) ## Settings ### Get Credit Balance Current credit balance information for **Plus** solver mode is available under ADVANCED_CELL_TOWER_LOCATION setting details. Get a list of customer settings: ```shell curl -X GET "https://api.1nce.com/management-api/v1/settings/1nceos" ``` The response could be `200 OK` with body: ```json { "items": [ { "state": "ENABLED", "details": { "credits": 100, "expiryDate": "2030-04-23T10:52:18.330Z" }, "name": "ADVANCED_CELL_TOWER_LOCATION", "description": "Improves the Cell Tower Location functionality, especially for 3G, 4G and LTE-M." } ], "page": 1, "pageAmount": 1 } ``` :::warning Note that `details` object with `credits` and `expiryDate` parameters is only available in Cell tower **Plus** mode. ::: ## Geofence ### Create geofence Create new geofence: ```shell curl -X POST "https://api.1nce.com/management-api/v1/locate/geofences" ``` The request body looks like this: ```json { "name": "Once", "eventTypes": [ "EXIT", "ENTER" ], "type": "polygon", "coordinates": [ [ [ 6.957239730898948, 50.93892367514573 ], [ 6.958509831039635, 50.93836584192053 ], [ 6.959702958010666, 50.93945723847878 ], [ 6.9596259993105605, 50.934266755623526 ], [ 6.961550428436993, 50.93431526288117 ], [ 6.961434941100492, 50.94059711468901 ], [ 6.959087148954154, 50.94059710732816 ], [ 6.957239730898948, 50.93892367514573 ] ] ], "eventSources": [ "GPS", "CellTower" ] } ``` ### Get Geofence Get details of a geofence. Get a details of geofence with id `geofence_id_1`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` The response could be `200 OK` with body: ```json { "id": "geofence_id_1", "name": "Once", "eventTypes": [ "EXIT", "ENTER" ], "coordinates": [ [ [ 6.95724, 50.938924 ], [ 6.95851, 50.938366 ], [ 6.959703, 50.939457 ], [ 6.959626, 50.934267 ], [ 6.96155, 50.934315 ], [ 6.961435, 50.940597 ], [ 6.959087, 50.940597 ], [ 6.95724, 50.938924 ] ] ], "type": "polygon", "eventSources": [ "GPS", "CellTower" ], "deviceId": null, "created": "2025-10-02T10:36:11.166Z", "updated": "2025-10-02T10:36:11.166Z" } ``` ### Get All Geofences Get a list of all customer geofences. ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/geofences" ``` The response could be `200 OK` with body: ```json { "items": [ { "id": "1jU_nQKeiEb_1tPt6EciD", "name": "Once", "created": "2025-09-09T07:00:58.126Z", "updated": "2025-09-09T07:00:58.126Z", "deviceId": "device123", "type": "polygon" }, { "id": "76luvK3qpxZKM136xnDNM", "name": "home", "created": "2025-09-10T12:28:20.576Z", "updated": "2025-09-10T12:28:20.576Z", "deviceId": null, "type": "polygon" } ], "page": 1, "pageAmount": 1 } ``` ### Patch Geofence Update an existing geofence You can change `eventTypes`, `eventSources` and `name` of existing geofence with id `geofence_id_1`: ```shell curl -X PATCH "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` The request body looks like this: ```json { "eventTypes": [ "ENTER", "EXIT" ], "eventSources": [ "CellTower", "GPS" ], "name": "Once2" } ``` :::warning Fields like `type`, `coordinates`, or `center` cannot be changed, instead you should delete old Geofence and create new one. ::: ### Delete Geofence Delete an existing geofence Delete geofence with id `geofence_id_1`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` ## Per-device Cell tower Plus The following endpoints allow managing Cell tower Plus on a per-device basis when CUSTOM mode is active. See [Per-device Cell tower Plus](/docs/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/) for the full workflow guide. ### Switch to CUSTOM Mode Switch the `ADVANCED_CELL_TOWER_LOCATION` setting to CUSTOM mode to enable per-device configuration: ```shell curl -X PATCH https://api.1nce.com/management-api/v1/settings/1nceos/ADVANCED_CELL_TOWER_LOCATION/details \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{"mode": "CUSTOM"}' ``` The response could be `200 OK` with body: ```json { "customerId": "12345", "name": "ADVANCED_CELL_TOWER_LOCATION", "state": "ENABLED", "details": { "mode": "CUSTOM" } } ``` ### Enable Cell tower Plus for Devices Enable Plus location resolution for specific devices. Requires CUSTOM mode to be active. ```shell curl -X POST https://api.1nce.com/management-api/v1/locate/devices/settings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{ "deviceIds": ["89012345678901234567", "89012345678901234568"], "details": { "frequency": 120 } }' ``` The response could be `200 OK` with body: ```json { "changedDeviceIds": ["89012345678901234567", "89012345678901234568"] } ``` :::warning The `changedDeviceIds` array lists only devices whose state actually changed. Devices already enabled or IDs that do not belong to your organization are silently excluded. ::: ### Get Per-Device Settings Query which devices have per-device Cell tower Plus enabled: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/settings/DEVICE_ADL?page=1&pageSize=20" \ -H "Authorization: Bearer {your_access_token}" ``` The response could be `200 OK` with body: ```json { "items": [ { "iccid": "89012345678901234567", "details": { "frequency": 120 } } ], "page": 1, "pageAmount": 1 } ``` Filter by a specific device: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/settings/DEVICE_ADL?iccid=89012345678901234567" \ -H "Authorization: Bearer {your_access_token}" ``` ### Disable Cell tower Plus for Devices Disable Plus location resolution for specific devices. Requires a JSON body with the DELETE request. ```shell curl -X DELETE https://api.1nce.com/management-api/v1/locate/devices/settings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{ "deviceIds": ["89012345678901234567", "89012345678901234568"] }' ``` The response could be `200 OK` with body: ```json { "changedDeviceIds": ["89012345678901234567", "89012345678901234568"] } ``` :::warning The `changedDeviceIds` array lists only devices whose state actually changed from enabled to disabled. ::: --- # Cell Tower Events Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/ ## Cell Tower Events table The Cell Tower Events tab on the Device Locator page lists the cell tower location resolution attempts for the selected device, retained for up to 7 days. Each row shows the event creation time, network access type (for example, LTE-M or NB-IoT), status (resolved by the Basic solver mode or the Plus solver mode), and resolver mode. ## What the Network Event Resolver is The Network Event Resolver re-runs cell tower location resolution with the Plus solver mode for one cell tower event you select on the Cell Tower Events tab. :::info The Network Event Resolver is a free tryout of the Plus solver mode and does not consume any Device Location Credits. The locations it produces are only for testing on demand and are not stored — the resolved data is lost when you close the "Cell tower event details" panel, navigate away, or close the browser tab. ::: Use it to re-resolve a single event that the Basic solver mode resolved imprecisely or failed to resolve, and see whether the higher-accuracy [Plus solver mode](/docs/1nce-os/1nce-os-device-locator/#plus-mode) does better — subject only to the [usage limits](#usage-limits-and-limit-reached-behavior) below. To use the Plus solver mode beyond the tryout, follow the "Upgrade to Plus" path to enable it and its [Device Location Credits](/docs/1nce-os/1nce-os-device-locator/#device-location-credits). To view resolution attempts through the API, use the [Get Device Activity](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity) endpoint. ## Per-event-type guide | Event type | On open | Resolve | |---|---|---| | Succeeded Basic | Red "Basic resolver" marker, detail fields, metadata JSON. | Enabled. | | Failed Basic | No marker plus "Resolve to see the location on the map.", detail fields, metadata JSON. | Enabled. | | Already Plus-resolved | View-only: blue "Plus resolver" marker with accuracy circle and resolved metadata. | Disabled (see [Restrictions](#restrictions)). | | NB-IoT | Detail fields and metadata. | Disabled (see [Restrictions](#restrictions)). | | Read-only role | Map, detail fields, metadata. | Not available. | ## Step-by-step walkthrough 1. Open the Cell Tower Events tab on the Device Locator page for the selected device. 2. Open the "Cell tower event details" panel for the event you want to re-resolve — either hover the row and select the details icon at its end, or select the row. The panel opens docked on the right.
![Cell Tower Events table with the details icon revealed on hover at the end of an event row, the entry point for the Network Event Resolver](/img/1nce-os/plus-resolver-on-demand/events-table-hover.png) Opening an event's details from the Cell Tower Events table.
3. Review the event detail fields: **Device ID (ICCID)**, **Mode**, **Status**, **Access technology**, and **"Cell tower event time"**.
![Cell tower event details panel in its initial state for a Basic event, showing the event detail fields, no resolved map pin, and the event-row metadata JSON](/img/1nce-os/plus-resolver-on-demand/basic-no-resolved-yet.png) The "Cell tower event details" panel before resolving.
4. Select "Resolve" to re-run resolution with the Plus solver mode. The panel shows a loading indicator while it runs, then "Resolve" is disabled — you get a single attempt per event, whether it succeeds or returns no location. 5. On a successful result, the map heading becomes "Map location (Resolved)" and shows the red "Basic resolver" before marker and the blue "Plus resolver" after marker (with an accuracy circle and a legend). If the before and resolved coordinates are identical, only the blue marker is shown.
![Successful on-demand resolution showing the Map location (Resolved) heading, a red Basic resolver before marker, a blue Plus resolver after marker with an accuracy circle, and the legend](/img/1nce-os/plus-resolver-on-demand/basic-resolved-on-demand.png) A successful on-demand Plus solver mode resolution.
6. On a no-location result, a "no location" message is shown, the before marker is retained, and the Status shows "Failed". This result is final and "Resolve" stays disabled.
![Completed on-demand resolution that returned no location, showing the no-location message, the retained before marker, and the Status shown as Failed](/img/1nce-os/plus-resolver-on-demand/on-demand-not-resolved.png) A resolution that returned no location.
7. Use the "View before resolution" / "View after resolution" toggle to switch the metadata between the original and resolved JSON ("Resolution Metadata" becomes "Resolution Metadata (After)", and the after view shows Status "Succeeded" / Mode "Plus"). Select "Copy" to copy the shown JSON.
![Before/after comparison showing the red Basic resolver marker and the blue Plus resolver marker together, the accuracy circle around the blue marker, and a legend listing both resolver rows under the Map location (Resolved) heading](/img/1nce-os/plus-resolver-on-demand/basic-to-plus-comparison.png) Comparing the Basic and Plus locations.
## Usage limits and limit-reached behavior On-demand resolution is capped at 3 resolutions per 60-minute window and 12 per 24-hour window; both apply at once. When you reach either cap, the attempt is blocked and a "Limit reached" dialog appears instead of a result. You cannot resolve again until your usage falls back within both caps.
![Limit reached dialog showing both limit rows, a limiter-specific title and description, a reset line, and the Upgrade to Plus call-to-action](/img/1nce-os/plus-resolver-on-demand/on-demand-rate-limited.png) The "Limit reached" dialog.
The dialog's title and description reflect which limit you reached, and — when a reset time is available — a line tells you when you can resolve again. On the Basic plan, the dialog also offers an "Upgrade to Plus" call-to-action (not shown if the Plus solver mode / ADL is already enabled). ## Restrictions - **NB-IoT is not supported.** For an NB-IoT event, "Resolve" is disabled with the message "Resolution is not available for NB-IoT devices." NB-IoT is the only blocked access type. - **Already resolved by the Plus solver mode.** The panel opens view-only with "Resolve" disabled and the tooltip "This event was already resolved with the Plus resolver." - **Read-only role.** You can open and view the panel, but "Resolve" is not rendered. - **The original event row never changes.** After any attempt, the row keeps its prior Failed or Basic state, whether the attempt succeeded or failed.
![Cell tower event details panel opened view-only for an event already resolved by the Plus solver mode, with the Mode shown as Plus and the disabled Resolve control showing the already-resolved-with-the-Plus-resolver tooltip](/img/1nce-os/plus-resolver-on-demand/plus-already-resolved.png) An event already resolved by the Plus solver mode (view-only).
--- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/device-locator-features-limitations/ ## Features ### Cell Tower Location (Basic and Plus) * The IoT Devices are located by using the cell id of the current tower when creating a new PDP Context or Session used for data transmission. In case the location cannot be determined, the update is skipped and a retry will be done in the next PDP Context/Session. * Using the API, device location and cell tower activity can be queried. The `DeviceId` is equal to the `ICCID`. * The resolved locations of a device can be queried using the [Get Device Positions](/api/1nce-os/get-device-positions/) endpoint. * The cell tower location resolution history (including unresolved records) can be queried using the [Get Device Activity](/api/1nce-os/get-device-celltower-location-resolutions/) endpoint. * Cell tower Plus location mode provides a metadata parameter with accuracy data for resolved locations and tower metadata for unresolved [locations](/docs/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity). * A Basic-plan customer can test Plus (advanced) resolution on demand with the [Network Event Resolver](/docs/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/), re-running resolution for a single cell-tower event that was previously resolved by the Basic solver mode (a succeeded event) or whose prior resolution failed, directly from the Cell Tower Events tab. ### Geofencing * Using Geofencing functionality it is possible to set virtual boundaries to detect geofence crossing event and receive a notification about it via the [Cloud integrator](/docs/1nce-os/1nce-os-cloud-integrator/). * Users can create up to 10 global geofences across all devices as well as 1 device-specific geofence per-device. * Geofences supports two area types: polygon and circle. * It is possible to define Geofence event types, which control if geofence events will be triggered on device entering or exiting specified area or on both, if not specified then default is to use both. * It is possible to define Geofence event sources, which control if geofence events will be triggered on GPS or Cell Tower location changes or on both, if not specified then default is to use both. * For the circle Geofence which is attached to the device, system will try to retrieve circle center using latest device location in case if user does not pass center during Geofence creation request. ### Per-device Cell tower Plus * Cell tower Plus can be configured on a per-device basis using CUSTOM mode, allowing selective enabling or disabling of Plus location resolution for individual devices via the API or the Plus Resolution tab in the portal. * Each device can have a configurable location resolution frequency between 60 and 1440 minutes. * Managing per-device Plus resolution via the Plus Resolution tab in the portal. * Selecting devices using Single ICCID input, ICCID Range expansion, or CSV file upload. * Configuring and updating frequency for individual or bulk devices. * Deleting per-device configurations individually from the table or in bulk via the Manage SIMs section. * Receiving batch operation results with partial failure feedback including downloadable failed ICCID lists. * See the [Per-device Cell tower Plus guide](/docs/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/) for step-by-step instructions. ## Limitations ### Cell Tower Location (Basic and Plus) * Cell tower **Basic** and **Plus** location modes use different data sources. Currently, Basic mode resolves approximately **30% of locations**, while Plus mode resolves **around 90%**. However, location data can be inaccurate, especially for 3G, 4G, LTE-M, and NB-IoT devices. * If Plus resolver mode is enabled, then [Device Location credits](/docs/1nce-os/1nce-os-device-locator/#device-location-credits) will be consumed. * NB-IoT locations are not being resolved with Plus resolver. * After activating the cell tower location setting it can take a few minutes before the first location will be available. * Cell tower location data is resolved no more frequently than once an hour. * For customers in Brazil and China, current service limitations may impact our ability to accurately determine device cell-tower location and maintain a complete location history. This may result in less accurate or incomplete location information. * To view the location history of specific device on the map you have to switch to the Device Inspector in the 1NCE OS Portal. * The Cell tower events tab displays data for a single device selected in the filter. * Network Event Resolver on-demand testing is rate-limited to at most 3 resolutions per hour and at most 12 within any 24-hour window; both limits apply. When either limit is reached, a "Limit reached" dialog blocks further attempts until usage falls back within the limits. * The Network Event Resolver on-demand result is transient and provided only for testing the Plus solver mode. It is not stored or persisted, and is lost when you close the "Cell tower event details" panel, navigate away, or close the browser tab. ### Geofencing * Polygon geofences support a maximum of 50 coordinate points (including the closing point). * Circle geofence radius must be between 50 m (minimum) and 30,000 m (maximum). * User can update only Geofence name, event types and event sources, coordinates and Geofence type cannot be changed to prevent possible confusion with the previous exit or enter events. * Geofence creation and enter/exit events require active [Geofence credits](/docs/1nce-os/1nce-os-device-locator/#geofence-credits). ### Per-device Cell tower Plus * Per-device Cell tower Plus requires the customer to have purchased Device Location credits. * Per-device Cell tower Plus requires the ADVANCED_CELL_TOWER_LOCATION setting to be enabled with mode set to CUSTOM. * A maximum of 100 device IDs can be enabled or disabled in a single batch operation (API request or portal submission). * Switching from CUSTOM to DEFAULT mode is not available through the API or the portal. * New SIMs activated in CUSTOM mode default to basic resolution until explicitly enabled via the API or the portal. * Per-device Cell tower Plus consumes Device Location credits, when credits are exhausted, resolutions stop but per-device configurations are preserved. * CSV file upload in the portal Plus Resolution tab is limited to 200 KB. --- # Geofence creation guide Source: https://help.1nce.com/docs/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/ ## Prerequisites Before creating geofences, ensure that [Geofence Credits](/docs/1nce-os/1nce-os-device-locator/#geofence-credits) are available in your account. Without active credits, geofence creation is not possible. ## Creating a Geofence To create a new geofence, click the **+ Create Geofence** button on the Device Locator page.
![Create Geofence button](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/create-geofence-button.png) *Create Geofence button*
### Scope Select the scope for the new geofence — **Global** or **Device Specific**. * **Global** geofences apply to all devices in your account. You can create up to 10 global geofences. * **Device Specific** geofences are tied to a single device (identified by ICCID). You can create 1 device-specific geofence per device.
![Geofence scope selection](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofence-scope.png) *Geofence scope selection*
### Name Enter a name for the geofence. :::info Naming convention for device-specific geofences For device-specific geofences, you can later filter geofences either by entering the full ICCID or by searching multiple geofences by name prefix. Choosing a consistent naming convention (e.g., a shared prefix like `warehouse-` or `fleet-`) makes it easier to find and manage groups of device-specific geofences. ::: ### Type Select the geofence shape — **Polygon** or **Circle**. * **Polygon** — draw the geofence boundary directly on the map by placing up to 50 coordinate points.
![Drawing a polygon geofence on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofene-polygon.png) *Polygon geofence*
* **Circle** — draw a circle around a selected center point on the map. The radius must be between 50 m and 30,000 m.
![Drawing a circle geofence on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofene-circle.png) *Circle geofence*
### Event Types Choose which crossing events should trigger a [geofence event](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/#geofence): * **Enter** — triggered when a device enters the geofence boundary * **Exit** — triggered when a device exits the geofence boundary * **Enter & Exit** — triggered on both entry and exit ### Event Sources Select the location data source used to evaluate geofence crossings: * **[Cell Tower](/docs/1nce-os/1nce-os-device-locator/#cell-tower-location)** — uses cell tower-based location data * **[GPS](/docs/1nce-os/1nce-os-device-locator/#gps-location)** — uses GPS coordinates reported by the device (via [Energy Saver](/docs/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/) or [LwM2M](/docs/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/)) * **Cell Tower & GPS** — evaluates against both sources ### ICCID (Device Specific only) Enter the ICCID of the device. The system can automatically determine the latest device location (if available). **Device location is available:** When creating a device-specific geofence with the Circle type, the system retrieves the latest known device location. To use this location as the center of the circle, click the location icon next to the filled ICCID field.
![Device-specific geofence with known location](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/device-specific-location-known.png) *Device location available*
**Device location is not available:** If the device does not have a known location, the system cannot automatically determine its position. You will need to draw the geofence boundary manually on the map.
![Device-specific geofence with unknown location](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/device-specific-location-unknown.png) *Device location not available*
## Viewing Geofences Besides viewing geofences in the portal, you can also retrieve the full list programmatically via the [Get all geofences](/api/1nce-os/get-all-geofences/) API endpoint. ### Global Geofences When the global geofences view is selected, all global geofences are loaded and shown in the dropdown list. All global geofences are also placed on the map.
![Viewing global geofences on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-global-geofences.png) *Global geofences view*
### Device Specific Geofences When looking for device-specific geofences, you can either enter the full ICCID or use a name prefix to filter results (up to 10 geofences will be shown). **By full ICCID:**
![Viewing device geofence by ICCID](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-device-geofence-by-iccid.png) *Filter by full ICCID*
**By name prefix:**
![Viewing device geofences by name prefix](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-device-geofence-by-prefix.png) *Filter by name prefix*
## Editing and Deleting Geofences By clicking on a geofence, you can view its details and choose to **Edit** or **Delete** it.
![Geofence details with Edit and Delete options](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-geofence-details.png) *Geofence details*
When editing a geofence, only the following fields can be changed: * **Name** * **Event Types** * **Event Sources** Coordinates and geofence type cannot be modified. To change the shape or location, delete the existing geofence and create a new one.
![Editing a geofence](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/edit-geofence.png) *Edit geofence*
## Quick Test: End-to-End Validation Ensure you have active [Geofence Credits](/docs/1nce-os/1nce-os-device-locator/#geofence-credits) before proceeding. Follow these steps to quickly validate that your geofence setup is working correctly. **1. Create a Cloud Integration** Set up a [Webhook Cloud Integration](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/#webhook-creation) and select **Geofence** as the Event Type. A temporary webhook (e.g., using [webhook.site](https://webhook.site)) is sufficient for testing purposes. **2. Simulate a GPS location for your device** Use the Energy Saver [template example](/docs/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/#template-example) to send a GPS location from your device. This establishes the initial device position. **3. Create a device-specific geofence using the device location** Create a device-specific circle geofence as described in the [ICCID section](#iccid-device-specific-only). The system will use the location reported in step 2 as the center of the geofence. **4. Simulate new GPS locations that enter and exit the geofence** Using the same Energy Saver template example, send GPS coordinates that are inside and then outside the geofence boundary. This triggers Enter and Exit events. **5. Validate geofence events in the Webhook** Check your webhook endpoint for incoming geofence events. You should see **ENTER** and/or **EXIT** events depending on the simulated locations and your geofence event type configuration. ## Retrieving Geofence events After geofence is created, [Cloud integrator](/docs/1nce-os/1nce-os-cloud-integrator/) will create **ENTER** and **EXIT** events on every geofence border crossing by device, depending on the configuration of geofence `eventTypes`, `eventSources` and also device location update frequency.
![Geofence EXIT event from GPS source](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/Geofence-event-in-aws-intergration.png) *Geofence EXIT event from GPS source in AWS Cloud Integration*
Please see [Cloud integrator output format](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format) for details of geofence events. --- # Energy Saver Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/ ![](/img/1nce-os/1nce-os-energy-saver/energy-saver.png) With the energy saver, 1NCE offers a simple way to decode freeform third-party binary payloads. With the help of BCL, JSON objects are created. This chapter will guide through the setup and usage process with full examples and code snippets. --- # Binary Conversion Language Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language/ The goal of the Binary Conversion Language (BCL) is to provide an easy way of defining a schema for decoding freeform third-party binary payloads. A set of mappings in BCL specific to a device type is called a conversion. Conversions are encoded as JSON objects. More details on the general conversion language available at [https://docs.allthingstalk.com/dl/AllThingsTalk\_Binary\_Conversion\_Language\_1\_0\_0.pdf](https://docs.allthingstalk.com/dl/AllThingsTalk_Binary_Conversion_Language_1_0_0.pdf) ## Structure of a conversion ```json Example: Home alarm system { "name": "alarm", "comment": "Home alarm system", "version": "1.0.0", "sense": [ { "asset": "motion", "value": { "byte": 0, "bytelength": 1, "type": "boolean" } } ] } ``` In this example, we declare a data conversion used with a home alarm system device. When the device senses motion it sends one byte to [UDP endpoint](/docs/1nce-os/1nce-os-device-integrator/device-integrator-udp/). This simple template converts that one byte sent by the device into a JSON object with a boolean field called `motion`. When the device with enabled binary translation, sends `0x01` the byte gets translated into `true` resulting in the following object: ```json { "motion": true } ``` ## Top-level fields A conversion MUST have a list field named `sense`, which contains statements that need to be evaluated during `sensing` - when de-serializing binary payloads into JSON objects. A conversion MAY have a string field named `comment`, provided for a human-readable description of the conversion. ## Statements Statements are JSON objects that describe a single operation that needs to be performed in a conversion. A statement MUST be either a mapping statement, a control statement, or a comment statement. Statements appear in statement blocks. ## Statement blocks Statement blocks are JSON lists whose elements are statements or statement blocks that need to be performed in order to complete the conversion. A statement block MAY contain no elements. Making a statement block empty is the same as omitting it all together - no statements get executed. This can be useful in code generation. There are two types of statement blocks: `sense` and `do`. `sense` statement blocks are executed when sensing (receiving data), and they are present in the home alarm example. `do` is used wherever embedding a statement block - usually within control structures - is needed. ## Sense block Sense block MAY contain mapping statements and control statements. Mapping statements in sense block MUST contain a string field `asset`, whose value is a string that uses JSON dot-notation to identify the path to the field in the resulting object. Mapping statements in sense block MUST contain a field `value`, whose value is a selector that identifies the data that will be stored as the new value of the asset. Mapping statements in sense block MAY have a string field named `comment`, provided for human-readable description of the given mapping. ## Mapping statements Mapping statements are used for de-serializing values and metadata from specific parts of binary payloads, special values, variables, and constants into fields in the resulting JSON. The statement contains two fields: `asset` - Path to resulting field using JSON dot notation\ `value` - Constant or payload selector Examples: **Inject a string field using the constant selector.** ```json Example - sense { "sense": [ { "asset": "sensor", "value": "motion" } ] } ``` Result: ```json Example - sense result { "sensor": "motion" } ``` **Convert 4 bytes into a 32-bit floating-point number using payload selector. Longitude from GPS beacon** ```json sense longitude example { "sense": [ { "asset": "longitude", "value": { "byte": 0, "bytelength": 4, "byteorder": "big", "type": "float" } } ] } ``` Data: - `42 4b bc f9` Result: ```json sense longitude example result { "longitude": 50.934544 } ``` ## Control statements Control statements MUST have a JSON object field named `switch` that specifies the payload selector that's going to be evaluated, and its value tested in cases. Control statements MUST have a JSON array field named `on` that contains a list of cases that switch value will be tested on, optionally including the default case. Control statements are used for executing control logic that MAY lead to executing more statements. The switch is the only available control statement in this version of BCL. Control statement MAY have a string field named `comment`, provided for human-readable description of the conversion. Control statement on list MAY contain zero or more case statements. The control statement on the list MAY contain a comment statement. ## Case statements The case statement MAY have a JSON object field named `case`, whose value is a selector whose value is tested with the switch selectors value in the outer switch control statement. If it is equal, `do` statement block is executed. The switch logic supports optional `default` case. If field `case` is not present in the case statement, a field `default` MUST be present with value `true` marking this object a default case of the switch. Case statement MUST have a JSON list field named `do`, whose value is a statement block that is executed if case and switch match. If no `case` statements match the payload, and the `default` case is defined, the default case is executed instead. If `default` case is not present and no `case` statements match, nothing is executed. Example: In this example, payload first byte is an 8-bit integer that defines message type. Message type 0 is positional data about the vehicle and message type 1 is maintenance data. Message type 0 has the following structure: ```text Message Structure Full Example +-------------------+------------------+-------------+ | 4 bytes | 4 bytes | 2 bytes | +-------------------+------------------+-------------+ | Longitude (float) | Latitude (float) | Speed (int) | +-------------------+------------------+-------------+ ``` Let's initialize the switch statement and create the condition for message type `0` ```json Full Example { "sense": [ { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "comment": "Positional data", "do": [ { "asset": "gps.lat", "value": { "byte": 1, "bytelength": 4, "byteorder": "big", "type": "float" } }, { "asset": "gps.lon", "value": { "byte": 5, "bytelength": 4, "byteorder": "big", "type": "float" } }, { "asset": "speed", "value": { "byte": 9, "bytelength": 2, "byteorder": "big", "type": "int" } } ] }, { "default": true, "do": [ { "asset": "error", "value": "unknown payload" } ] } ] } ] } ``` Device sends the following data `00 42 4b bc f9 40 de 98 1c 00 78` First byte `00` determines that this message contains positional data. The message will result in the following object: ```json Full Example Result { "gps": { "lat": 50.934544, "lon": 6.956068 }, "speed": 120 } ``` If device sends the following data `01 ff ff ff`, the first byte `01` does not match the defined case statement, meaning the default statement is executed: ```json Full Example Result { "error": "unknown payload" } ``` ## Selectors Selectors are JSON values. They are used to “select” data from a given location type or “select” data used in a control statement. Selectors MAY have a string field named `comment`, provided for human-readable description of the conversion. ## Constant selector The constant selector is a string. Example: ```text "foo" ``` ## Payload selector A payload selector is a JSON object. Payload selector MUST have an integer field named `byte` AND/OR an integer field named `endbyte`. The value of `byte` field represents the starting byte from which the chunk is going to be selected (counting from the beginning of the payload). The value of `endbyte` represents a byte counting from the end of the payload and is described as a value that is less or equal to zero. If both `byte` and `endbyte` are present in the payload selector, they are representing a range selector "from `byte` to `endbyte`". Payload selector MAY have an integer field named `bytelength`, whose value represents the length of the chunk in bytes, starting from and including the byte indexed by `byte` field. It defaults to 1. The field `bytelength` MUST NOT be present if the payload selector contains both `byte` and `endbyte`. Payload selector MAY have a string field named `byteorder`, whose value represents the byte order of the chunk of bytes. Values for this field can be `big` (Big Endian) or `little` (Little Endian). This value defaults to the `big`. Payload selector MUST have an integer field named `type`, which defined the data type to which bytes should be converted. Examples: Select 16-bit integer with little endian: ```json 16-bit integer select { "byte": 1, "bytelength": 2, "type": "int", "byteorder": "little" } ``` Select whole payload as a hex string: ```json whole payload section { "byte": 0, "endbyte": 0, "type": "hex" } ``` Select the last 4 bytes of the payload as a 32-bit unsigned integer (Big Endian by default): ```json last 4 bytes as 32-bit uint { "endbyte": -4, "bytelength": 4, "type": "uint" } ``` Supported data types **Numeric** `bytelength` is required. A fix was provided to use the default value of 1 byte if `bytelength` field is not provided inside selectors. `int` - signed integer. Can have `bytelength` 1, 2, 4, 8 which are 8-bit to 64-bit integers respectively. Defaults to 1\ `uint` - unsigned integer. Same constraints as `int`. ```text int and unit value ranges int and uint value ranges uint8 : 0 to 255 uint16 : 0 to 65535 uint32 : 0 to 4294967295 uint64 : 0 to 18446744073709551615 int8 : -128 to 127 int16 : -32768 to 32767 int32 : -2147483648 to 2147483647 int64 : -9223372036854775808 to 9223372036854775807 ``` `float` - floating-point number. Can have `bytelength` 4 and 8 which are 32-bit floating-point number and 64-bit double precision floating-point number. **Boolean** `boolean` - boolean. 0x00 will be treated as false. **String** `string` - UTF-8 encoded string. **Hex** `hex` - output as hex string. ## Nested structure Dot notation can be used to create JSON with a nested structure. ```json Example - nested { "sense": [ { "asset": "simple_key", "value": "value1" }, { "asset": "level1.level2.level3.level4", "value": "value2" } ] } ``` ```json Result - nested { "message": { "level1": { "level2": { "level3": { "level4": "value2" } } }, "simple_key": "value1" } } ``` ## Full Example Let's now fully expand all the pieces that we've talked about in this document. ```json Full Example { "sense": [ { "asset": "message_code", "value": { "byte": 0, "bytelength": 1, "type": "uint" } }, { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "comment": "Positional data", "do": [ { "asset": "data_type", "value": "Position" }, { "asset": "gps.lat", "value": { "byte": 1, "bytelength": 4, "type": "float" } }, { "asset": "gps.lon", "value": { "byte": 4, "bytelength": 4, "type": "float" } }, { "asset": "speed", "value": { "byte": 8, "bytelength": 2, "type": "int" } } ] }, { "case": 1, "comment": "Maintenance data", "do": [ { "asset": "data_type", "value": "Maintenance" }, { "asset": "on", "value": { "byte": 1, "type": "boolean" } }, { "asset": "fuel", "value": { "byte": 2, "bytelength": 4, "type": "uint" } }, { "asset": "driver", "value": { "byte": 6, "bytelength": 4, "type": "string" } }, { "asset": "driver_hex", "value": { "byte": 6, "bytelength": 4, "type": "hex" } } ] }, { "default": true, "do": [ { "asset": "data_type", "value": "Unsupported type" } ] } ] }, { "asset": "full_payload", "value": { "byte": 0, "endbyte": 0, "type": "hex" } } ] } ``` As before, this template parses two types of messages indicated by the first byte. In the beginning, though there is a new mapping statement that adds message type to the resulting JSON. In the switch block, a new statement is added to parse maintenance data. Data: `01 01 00 00 05 8c 6f 6c 65 67` The first byte is always mapped to `message_code`. Field `data_type` is a constant selector that will be evaluated to `Maintenance`. `0x01` -> 1 The message therefore should be parsed as maintenance data. We have already tried parsing Positional data, the example can be found above. Let's explore how the `switch` statement will work in this case. The byte at position 1 is parsed as a boolean and mapped to on, which determines if the vehicle is powered on. `0x01` -> true Next, fuel level is parsed from four bytes starting at position 2 and mapped to field `fuel`. Fuel will be parsed as `unit`, which is an unsigned integer because fuel can't drop below 0. Since 4 bytes is selected, the number will be parsed into 32-bit uint. `0x0000058c` -> 1420 Driver name is then parsed as a string. Name is parsed from 4 bytes starting from position 6. `0x6f6c6567` -> "oleg" Driver name is also outputted as hex string and mapped to field `driver_hex`. `0x6f6c6567` -> `6f6c6567` We also are adding the whole original payload to the output as hex in the field called `full_payload`. We are selecting the whole payload by defining the start of the selector as `byte: 0` and the end as `endbyte: 0`. We get the following result for our Translated Binary Payload. ```json Full Example - Result { "message_code": 1, "data_type": "Maintenance", "on": true, "fuel": 1420, "driver": "oleg", "driver_hex": "6f6c6567", "full_payload": "01010000058c6f6c6567" } ``` --- # Device Locator Integration Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/ It is possible for the device to send binary messages, use the Energy Saver to decode these messages, and send valid GPS data to the [device locator](/docs/1nce-os/1nce-os-device-locator/) service.\ To accomplish this integration, it is required to create an Energy Saver template and include the `custom_type` in the JSON template with the names `location_lat` and `location_long` to mark the latitude and longitude values respectively.\ GPS data can be: * Visualized in the 1NCE OS portal [device inspector](/docs/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations) & [device locator](/docs/1nce-os/1nce-os-device-locator/) tabs. * Used via [API](/docs/1nce-os/1nce-os-device-locator/device-locator-api). * Forwarded to [cloud integrator](/docs/1nce-os/1nce-os-cloud-integrator/). ### Template example **Energy Saver** template to decode longitude in the first 8 bytes and latitude in the subsequent 8 bytes of the message. ```json { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` ### Code snippet Example of generating a GPS payload: * Sends to the 1NCE OS UDP endpoint as a binary payload. * Prints the payload in Base64 format for testing with the Energy Saver template on the 1NCE OS portal or via the [API](/api/1nce-os/test-template). ```javascript const dgram = require('dgram'); // Server and message configuration const serverPort = 4445; const serverAddress = 'udp.os.1nce.com'; const latitude = 56.946285; const longitude = 24.105078; function encodeLocation(latitude, longitude) { const latBuff = processFloat(latitude); const longBuff = processFloat(longitude); return Buffer.concat([longBuff, latBuff]); } function processFloat(val) { // Assign the same byte length as defined in the template let buf = Buffer.alloc(8); buf.writeDoubleLE(val); return buf; } const message = encodeLocation(latitude, longitude); const client = dgram.createSocket('udp4'); client.send(message, serverPort, serverAddress, (err) => { if (err) { console.error('Error sending message:', err); } else { console.log('UDP message sent successfully as binary payload!'); } client.close(); }); console.log("Payload in base64 format for energy saver template testing in 1NCE OS Portal or via API:", message.toString('base64')); ``` --- # Energy Saving Calculation Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation/ By using the 1NCE Energy Saver with a translation template, the devices can save energy. How much energy is saved, depends on the optimized payload compared to the original full JSON. Below is a description of how the saved energy for 1NCE customers can be calculated based on 1NCE research. The research focusses on the impact of the energy saver on correlation of the translation compared to the usage of the battery. The tests were executed sending CoAP-Messages with translation capabilities in various degrees. # Test-Setup Tools used: * Testing device: NRF Development kit (Nordic nRF9160-DK) * Device power measurement: Qoitech Otii arc Testing rules: * Energy saver using CoAPs (NB-IoT – stable connection) * Incremental payload (50B – 2KB) * Duration of Test: 3 hours * Frequency of messages: 4 messages/minute # Result Measurements: | Payload Size (Bytes) | 1st Hour | 2nd Hour | 3rd Hour | Average consumption (mWh) | | :------------------- | :------- | :------- | :------- | :------------------------ | | **50** | 94.5 | 95 | 92.3 | 93.1 | | **250** | 101 | 98 | 95.1 | 98.0 | | **500** | 101 | 101 | 98.1 | 100.0 | | **1000** | 107 | 106 | 111 | 108.0 | | **1500** | 112 | 113 | 117 | 114.0 | | **2000** | 121 | 118 | 119 | 119.3 | ![Payload vs. Consumption](/img/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation/energy-used-graph.png) The energy consumption of the IoT device can be calculated by: **E = 0.013 x + 94.084** Where **E** is the energy consumption and **x** ist the Payload in Bytes. For every Byte less in communication you save an average of 0.013 mWh. `
`Ereduced = E(xoriginal) - E(xoptimized)`
`
  • xoptimized is the payload from the device that is using a translation template
  • xoriginal is the value that will result after the optimized payload is translated (full JSON string)
The average amount of saved energy is the difference between the energy consumption of the full JSON and the energy consumption of the optimized payload. Please be aware that the average amount of saved energy is an estimated value and not an actual measurement. In the tests, the payload was varied in all experiments to avoid caching by network (or software). # Example Payload ```Text base64 00 1A 00 37 00 ``` Output ```Text Optimized JSON { "Temperature": 26, "Humidity": 55, "Switch": FALSE } ```
  • Payload = 10 Bytes (xoptimized)
  • Output = 47 Bytes (xoriginal)
  • Amount of Saved Bytes = 37 Bytes
  • Energy Saved (Ereduced) = 0.481 mWh
Compared to the energy of the original payload we save 0.51% of energy in this example. General rule of thumb, small payloads only result in a small energy saving. The larger the payload and the greater the optimization, the more energy is saved. --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/energy-saver-features-limitations/ ## Features The 1NCE Energy Saver offers binary conversion inspired on the AllThings Talk Binary Conversion Language (ABCL) but we don't support all the all features. More details on the general conversion language available at [Binary Conversion Language](/docs/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language) The binary conversion allows customers to simply format binary payloads and build also more complex logic into the conversion templates. Templates are provided via the 1NCE Energy Saver and applied to the desired Devices.\ Let's take the following example for a simple IoT device with 2 sensors one input. A UDP payload would look like this: **00 1A 00 37 00** As this is not readable let's apply the following conversion template to the message: ```json { "sense": [ { "asset": "Temperature", "value": { "byte": 0, "bytelength": 2, "type": "int", "signed": true } }, { "asset": "Humidity", "value": { "byte": 2, "bytelength": 2, "type": "int" } }, { "asset": "Switch", "value": { "byte": 4, "type": "boolean" } } ] } ``` This will result in a nicely formatted JSON-message that is also human-readable: ```json { "Temperature": 26, "Humidity": 55, "Switch": false } ``` Desired template can be edited and tested using [Template Tester](/docs/1nce-os/1nce-os-energy-saver/energy-saver-template-tester) ## Limitations * Only values between -9999999999999999 and 9999999999999999 are guaranteed to have the correct precision. Values smaller than -9999999999999999 and larger than 9999999999999999 could be affected by rounding precision. * API requests have a maximum request body size limit of 64kb, which includes all the information sent in the request body. This limitation can potentially affect requests to [create](/api/1nce-os/create-optimizer-template/) and [patch](/api/1nce-os/update-optimizer-template/) template endpoints, since the size of the template and other information sent in the request body cannot exceed 64kb. * Only 1 **Energy Saver** template is allowed per protocol (UDP and CoAP). --- # Template tester Source: https://help.1nce.com/docs/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/ # Edit and Test To help with creating optimized translation templates for your needs to meet best energy and data saving expectation 1NCE OS provides: * an interface to **Edit and Test** the desired template. * [API](/api/1nce-os/test-template) endpoint to test the template. Template tester is a tool that processes the given **Binary** payload in Base64 string format using the template in template editor and returns the JSON output, translating the Base64 binary payload into readable format. Note that Base64 string binary representation is used only for testing purpose, the actual translation of message is done from **Binary** into **JSON**.\ Also, until changes are saved and template is in active state the template changes does not affect the flow of CoAP or UDP messages.
![Edit and Test template interface](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/template-edit-and-test.png)
# Example templates There are 3 example templates provided to start with or just create your own template from scratch. To try example templates just expand the list of example templates, select any desired template and press **Use this template** button. It will insert example template into template editor, provide example payload into input field. Now you are ready to do the template testing.
![Example templates](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/example-templates.png)
### Location template ``` { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` If custom types location\_long and location\_lat are available the position will be forwarded to the [Location Service](/docs/1nce-os/1nce-os-device-locator/). Longitude and latitude both have to be float64. ### Deep JSON ``` { "sense": [ { "asset": "car.running", "value": { "byte": 0, "type": "boolean" } }, { "asset": "car.fuel", "value": { "byte": 1, "bytelength": 4, "type": "uint" } }, { "asset": "car.driver", "value": { "byte": 5, "bytelength": 4, "type": "string" } } ] } ``` By including dots in the asset name, deep JSON objects can be created. ### Switch statement ``` { "sense": [ { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "do": [ { "asset": "data_type", "value": "environment" }, { "asset": "temperature", "value": { "byte": 1, "bytelength": 4, "type": "float" } } ] }, { "case": 1, "do": [ { "asset": "data_type", "value": "device" }, { "asset": "on", "value": { "byte": 1, "type": "boolean" } } ] } ] } ] } ``` The [statements](/docs/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language#case-statements) inside do will be executed if the value of case (within the same object as do) and the switch match. # Test results ## Test failed When template is incorrect and template tester can't process the payload, the error message appears under the edit field describing the error:
![Template expects 17 bytes while only 16 bytes are provided](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/invalid-template.png)
## Test succeeded Output field below template editor provides the translated template value in readable format. As an additional template performance metrics the **Reduced Bytes** is provided that represents payload size difference between OUTPUT and INPUT of template as well as **Energy Saved** value that is calculated according to our research described in [Energy Saving Calculation](/docs/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation) article. Reduced bytes and Energy saved metrics represents savings on every message that is sent by device
![Test succeeded](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/template-metrics.png)
--- # LwM2M Service Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-overview.png)
Lightweight M2M (LwM2M) is a protocol standard specified by the Open Mobile Alliance (OMA LwM2M) with the goal to offer a fast client-server specification for Machine-to-Machine (M2M) and Internet of Things (IoT) communication and management services. LwM2M defines an application layer protocol between any arbitrary client (e.g., IoT device with 1NCE OS) and a LwM2M server (e.g., 1NCE OS LwM2M Integration). Exchanging data by using the light and secure LwM2M communication interface along with the efficient data model, enables device management and service enablement for constrained IoT and M2M devices. The unified LwM2M protocol standard makes it possible to bring a wide range of supported LwM2M devices from different vendors and application categories together and integrate these connected devices into one common communication and management interface. The LwM2M specification provides general APIs for device configuration, connectivity monitoring/statistics, security and firmware update, server provisioning and is constantly extended. The widely used Constrained Application Protocol (CoAP) provides in-built binding for LwM2M, thus making the LwM2M protocol particularly appealing for the Internet of Things (IoT) using mobile connectivity. The standard is targeted, in particular, at constrained devices, e.g., devices with low-power microcontrollers and small amounts of Flash and RAM over networks requiring efficient bandwidth usage. At the same time, LwM2M can also be utilized with more powerful embedded devices that benefit from efficient communication. The first release of LwM2M 1.0 dates back to February 2017. Since then, regular feature and maintenance updates have been released. Currently LwM2M 1.2 represents the current standard. To get updates on the latest developments, please visit the OMA LwM2M website. A large consortium of well-known IoT hardware and software manufacturers have committed resources to enhance and further develop the LwM2M standard in their products. To this day, many LwM2M application notes from mobile network modem and connectivity device manufactures have been released. The addition of LwM2M to the portfolio of the 1NCE Services allows 1NCE customers to directly use LwM2M as part of their IoT device integration and management. The following chapters outline the features and limitations of the 1NCE LwM2M service, provide a basic introduction into LwM2M and offer a range of use case examples to get you successfully started using 1NCE Connect in combination with the 1NCE LwM2M Service. --- # Bootstrapping Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping/ To use the 1NCE LwM2M Service, every time a client IoT device with a 1NCE SIM wants to connect or reattach, the bootstrap server needs to be contacted at first. A direct connection to the LwM2M server without prior communication towards the bootstrap service is not possible. The task at hand for the bootstrap server is to accept the initial connection, handle the authorization of the SIM device using the SIM-as-an-Identity service and provide LwM2M server connectivity instructions with one-time specific security credentials. There are two possible methods to bootstrap a device. The bootstrapping can be performed either by encrypted DTLS communication (using PSK) or by using Plain COAP. DTLS is using pre-shared key (PSK) provided by client device and identity of device (deviceId-iccid). If device is bootstrapping to secure server, the LWM2M server priority is changed to also secure server to be first. The PSK can be set: * using 1NCE OS API endpoint described in [API Explorer](/api/1nce-os/create-pre-shared-device-key/) * in 1NCE OS portal Device Integrator when [testing lwm2m endpoint](/docs/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints#testing-the-endpoint) Using [leshan client](https://github.com/eclipse/leshan#test-leshan-demos-locally) there is 2 examples to bootstrap: 1. **DTLS** `java -jar .\leshan-client.jar -b -u lwm2m.os.1nce.com:5684 -p -i ` 2. **PLAIN** `java -jar .\leshan-client.jar -b -u lwm2m.os.1nce.com:5683` The following figure illustrates this process in detail.
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping/lwm2m-bootstrapping.png)
### The shown steps are the following (plain connection): 1. The LwM2M client calls the bootstrap server at `lwm2m.os.1nce.com:5683` using plain CoAP. 2. The bootstrap server responds with a data message containing all the necessary information for the client to connect to the actual LwM2M server. **LwM2M Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/0/0 | LWM2M Server URI | String | Example: `coap://1.2.3.4:5683` | | 0/0/1 | Bootstrap-Server | Boolean | false | | 0/0/2 | Security Mode | Integer | 3 (NoSec) | | 0/0/10 | Server Id | Integer | 1111 | | 1/0/0 | Short Server ID | Integer | 1111 | | 1/0/1 | Lifetime (s) | Integer | 86400 | | 1/0/2 | Default Minimum Period (s) | Integer | 1 | **Bootstrap Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/1/0 | Bootstrap Server URI | String | Example: `coap://lwm2m.os.1nce.com:5683` | | 0/1/1 | Bootstrap-Server | Boolean | yes | | 0/1/2 | Security Mode | Integer | 3 (NoSec) | | 0/1/10 | Server Id | Integer | 2222 | 3. The LwM2M client device uses this information to trigger the registration on the LwM2M server using CoAP. ### The shown steps are the following (with DTLS): 1. The LwM2M client calls the bootstrap server at lwm2m.os.1nce.com:5684 using CoAPs. 2. The bootstrap server responds with a data message containing all the necessary information for the client to connect to the actual LwM2M server. **LwM2M DTLS Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/0/0 | LWM2M Server URI | String | Example: `coaps://1.2.3.4:5684` | | 0/0/1 | Bootstrap-Server | Boolean | false | | 0/0/2 | Security Mode | Integer | 0 (Pre-Shared Key) | | 0/0/3 | Identity | Opaque | *Identity as binary data* | | 0/0/5 | Secret Key | Opaque | *Private key for LwM2M Server as binary data* | | 0/0/10 | Server Id | Integer | 1111 | | 1/0/0 | Short Server ID | Integer | 1111 | | 1/0/1 | Lifetime (s) | Integer | 86400 | | 1/0/2 | Default Minimum Period (s) | Integer | 1 | **Bootstrap DTLS Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/1/0 | Bootstrap Server URI | String | Example: `coaps://lwm2m.os.1nce.com:5684` | | 0/1/1 | Bootstrap-Server | Boolean | yes | | 0/1/2 | Security Mode | Integer | 0 (Pre-Shared Key) | | 0/1/3 | Identity | Opaque | *Identity as binary data* | | 0/1/5 | Secret Key | Opaque | *Private key for LwM2M Bootstrap Server as binary data* | | 0/1/10 | Server Id | Integer | 2222 | 3. The LwM2M client device uses this information to trigger the registration on the LwM2M server using CoAPs. The DTLS Pre Shared Key (PSK) that is provided by the bootstrap server and used for the registration is regenerated on every bootstrap request. --- # LwM2M Service Client Example Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/lwm2m-client-examples/ > ❗️ 1NCE SIM Connectivity > > For running the examples, a device/system with a 1NCE SIM that has an active data session connection needs to be used to send the request towards the 1NCE Services. The data traffic needs to be issued via the mobile network connection. Two commonly used LwM2M Clients are Eclipse Leshan (JAVA) and Eclipse Wakaama (C). This example section covers a basic guide for both LwM2M implementations on how to use them with the 1NCE LwM2M Service. # Eclipse Leshan Please review the Leshan GitHub page for reference. The Leshan Client Demo can be built as a Java Maven project. The JAVA client can be started with the following settings: ```shell java -jar ./target/leshan-client-demo-2.0.0-SNAPSHOT-jar-with-dependencies.jar -b -u lwm2m.os.1nce.com:5683 ``` To emulate a Send Operation, enter the `send 6` operation. To change the frequency of registration updates, in the Leshan client `DefaultRegistrationEngineFactory` should be updated with a specific communication period (example, make registration update trigger every 30 seconds): ```java LeshanClientBuilder builder = new LeshanClientBuilder(cli.main.endpoint); ... // Configure Registration Engine DefaultRegistrationEngineFactory engineFactory = new DefaultRegistrationEngineFactory(); ... engineFactory.setCommunicationPeriod(30000); ... builder.setRegistrationEngineFactory(engineFactory); ``` *** # Eclipse Wakaama Please review the Wakaama GitHub page for reference.\ Wakaama has a Client Example GitHub which should be built as instructed and started with: ```shell ./lwm2mclient -b -h lwm2m.os.1nce.com -p 5683 -4 ``` --- # Data Handling Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/lwm2m-flow.png)
In general, there are two options how data from a LwM2M client device can be transmitted towards the LwM2M Server. The send operation represents the push-orientated communication, whereas passive reporting reflects the pull-based data exchange. In the following section, both these data exchange methods are outlined. Further an outline to viewing and accessing the LwM2M data and further references are provided. *** # Send Operation An active LwM2M client that is registered on the LwM2M server can send data by executing a simple send operation. This send is used by the LwM2M client to "push" data to the LwM2M server without an explicit request by this server. This operation is used by the client to report values for resources and resource instances of known and existing LwM2M object instance(s) (OMA LwM2M Registry.) to the LwM2M Server. *** # Passive Reporting Passive reporting provides a pull-based data collection method, where data is requested from a LwM2M device. By enabling passive reports, the 1NCE LwM2M server tries to read all known readable objects of the LwM2M client. This read is timed based on the registration and registration update events. The read out data is also provided via the IoT Integrator. An object is considered readable if at least one of its resources is readable. LwM2M object IDs 1, 2, and 3 are excluded from this read operation. ## Enable Reporting To use passive reporting with the 1NCE LwM2M Service, the `LWM2M_PASSIVE_REPORTING` setting needs to be enabled. Setting can be enabled in 1NCE portal [Device integrator](/docs/1nce-os/1nce-os-device-integrator/).
![LwM2M Passive Reporting setting](/img/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/lwm2m-passive-reporting.png)
The setting can be enabled also with a [management API call](/api/1nce-os/patch-settings) ```shell curl --request PATCH \ --url https://api.1nce.com/management-api/v1/settings/1nceos/LWM2M_PASSIVE_REPORTING \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data '{"state": "ENABLED"}' ``` ## Reporting Example Suppose the used device support LwM2M object IDs 6 (Location) and 7 (Connectivity Statistics). Based on the registration and registration update, the LwM2M server would read all resources from objects 6 and 7 of the given client device. ## Reporting Interval By default, the registration lifetime and thus the update proposed by the LwM2M bootstrap server is **ONE day**. This would result in infrequent data updates when using passive reporting. To change this parameter to a higher registration update frequency, the LwM2M client needs to update the registration update frequency, though it should not exceed 1 day. *** # Action API With the Action API you get the possibility to automate actions in your device. Your device has to be registered on the LwM2M-Server. It is supporting following actions: * Read * Write * Execute * Observe (Defined as start and end) The actions are processed by an asynchronous API. To receive the results of your actions (read & observe), you can use the [Device Inspector](/docs/1nce-os/1nce-os-device-inspector/). If your requests fail, you can see the messages in the [Admin Logs](/docs/1nce-os/1nce-os-admin-logs/). Messages are forwarded to your cloud integrations as well when they are configured. For more information about the Action API visit the [Device Controller](/docs/1nce-os/1nce-os-device-controller/). Example Request (Within this example checking the state of a LED): ```shell curl --request POST \ --url https://api.1nce.com/management-api/v1/integrate/devices/821756382750126453/actions/LWM2M \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data '{ "action": "read", "resourceAddress": "/3311/0/5850" }' ``` This will be the result of such message you will find in the Cloud Integrator or Device Inspector. ```json { "/3311/0/5850": false } ``` This means that the LED is off. More codes for resourceAddress can be found [here](https://technical.openmobilealliance.org/OMNA/LwM2M/LwM2MRegistry.html). --- # Device Locator Integration Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/ # LwM2M Integration with Location Service LwM2M Server will automaticaly forward GPS data to [Device locator](/docs/1nce-os/1nce-os-device-locator/), if GPS data will be provided in following [OMA](https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/6.xml) resource addresses: * `/6/0/0` (latitude, Float) * `/6/0/1` (longitude, Float) * `/6/0/5` (timestamp, Time). Not mandatory. GPS data can be: * Visualized in the 1NCE OS portal [Device inspector](/docs/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations) & [Device locator](/docs/1nce-os/1nce-os-device-locator/) tabs. * Forwarded to [Cloud integrator](/docs/1nce-os/1nce-os-cloud-integrator/). * Used via [API](/docs/1nce-os/1nce-os-device-locator/device-locator-api).
![Location data from LwM2M Device in Historian](/img/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/lwm2m-gps-location-payload.png)
![GPS Location in Device Locator from LwM2M data](/img/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/lwm2m-gps-location-map.png)
--- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-lwm2m/lwm2m-features-limitations/ # 1NCE LwM2M Interfaces At the base for the LwM2M protocol stack lies the client (e.g., IoT device) and the LwM2M server infrastructure. ## Bootstrap Server The [1NCE Bootstrap Service](/docs/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping) for LwM2M serves as a fully automated management entity for keys, access control, and configuration required to enroll an IoT device with the 1NCE LwM2M Service. This component is based in the background on the [Device Authenticator](/docs/1nce-os/1nce-os-device-authenticator/) Service to automate the LwM2M bootstring with a 1NCE SIM card. ## LwM2M Server Once a connected IoT LwM2M device completed the bootstrapping process, a device can connect and register to the 1NCE LwM2M Server. This registration lets the LWM2M server know of the connected IoT device existence and its registered capability. ## Integration Test If an IoT device is registered with the 1NCE LwM2M Server, the individual device can be [tested](/docs/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints#testing-the-endpoint) in the Device Integrator. If the LwM2M Integration is setup, the connection can be tested with any device. Select one of the preferred Blueprints. More information about the Blueprints can be found ind [1NCE SDK & Blueprints](/docs/1nce-os/1nce-os-sdk-blueprints/). The ICCID of the device used for testing and optional the Pre-shared Key (PSK) is needed for the test setup. After setting up the testbed, a message has to be sent from the IoT SIM device. Please be aware that it can take up to 30 seconds to be received. ## LwM2M Data Reporting The 1NCE LwM2M Service enables registered devices to report information to the LwM2M server. All messages are forwarded and stored in the [Device Inspector](/docs/1nce-os/1nce-os-device-inspector/). This service stores the received information and provides data for the visualization via the management user interface and regular event updates via the management API. *** # Features * Using 1NCE SIM connectivity, LwM2M is not bound to any specific Radio Network Type (RAT) and will work with any available communication (2G, 3G, 4G, NB-IoT, CAT-M). * The 1NCE LwM2M Service uses the Device Inspector to store the current and past device states. Further the 1NCE admin logs stores the LwM2M messages received from any registered and connected device. The state and message information can be retrieved using the management user interface or the management API. * The communication with the 1NCE LwM2M server is secured via DTLS using Pre-Shared Keys (PSK). The PSK is regenerated for each device registration. * All Open Mobile Alliance (OMA) publicly defined LwM2M objects are supported. To see the full list, please reference the OMA lwm2m-registry. * Custom LwM2M object support is available upon request. Please contact [1NCE support](https://www.1nce.com/en-eu/support/contact) and submit the object definition XML files. The following requirements apply: - The object IDs must fall within an OMNA Vendor Bulk Reservation assigned to the organization (refer to [OMNA Vendor Bulk Reservations registry](https://www.openmobilealliance.org/specifications/registries/vendor-bulk-reservations)). - The object definition must be validated against the declared OMA LwM2M XML schema. Supported schemas are [LWM2M.xsd](http://openmobilealliance.org/tech/profiles/LWM2M.xsd) and [LWM2M-v1_1.xsd](http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd). * Bootstrapping can be performed either by CoAP or CoAPs (with PSK). *** # Limitations * LwM2M Endpoints are required to be [activated](/docs/1nce-os/1nce-os-device-integrator/), otherwise 1NCE LwM2M bootstrap server will not authorize devices. * LwM2M clients used with the 1NCE Service need to support v1.1 at least partially. * All LwM2M clients are required to do the bootstrapping process in order to access the 1NCE\ LwM2M server. A direct connection to the server is not possible. * If the LwM2M client device loses the connection to the LwM2M server (e.g., network reregistration, time-outs, device sleep, etc.), it needs to initiate the bootstrapping once process again. * LwM2M action API is asynchronous. Customers will not receive direct feedback from the device. --- # Plugin System Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/
![1NCE OS Plugin System](/img/1nce-os/1nce-os-plugins/plugin-system.png)
Plugins extend the capabilities of the 1NCE platform with services provided by 3rd party vendors. You can enable additional functionality by installing a plugin.
![Plugin System in 1NCE.com portal](/img/1nce-os/1nce-os-plugins/plugins-overview.png)
Available plugins: * **Datacake** - Device and Network data visualization in pre-made or custom dashboards. * **Mender** - Firmware Over-the-Air Management. * **Tartabit** - IoT Bridge with Azure, AWS, and GCP. * **Memfault** - Device Observability with Fault Diagnostics and Log management. --- # Azure Integration Plugin by Tartabit Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/ ## Description Tartabit IoT Bridge 1NCE OS Plugin swiftly integrates LPWAN devices provisioned on the 1NCE network and 1NCE OS, with customer applications running on major cloud platforms like Azure, AWS, and GCP. IoT Bridge ensures seamless connectivity via a low/no-code environment, enabling rapid deployment of production-grade IoT solutions. IoT Bridge alleviates the need to host custom servers and self-managed infrastructure. Service integrations include: **Azure** - IoT Hub, IoT Central, Digital Twin, CosmosDB, Data Explorer, Event Hub, Service Bus, Log Analytics, SQL, Maps **AWS** - IoT Core, Kinesis, Firehose, SQS, DocumentDB, DynamoDB, RDS **GCP** - Pub/Sub, Firebase, Cloud SQL, Maps **Open-source** - Kafka, AMQP, RabbitMQ, MQTT, webhooks Bottom line, if you are trying to build a world class Internet of Things solution based on LWPAN technologies then IoT Bridge, the industry’s easiest to use, easiest to buy, and easiest to deploy cloud gateway, will accelerate your time to market and reduce your development costs. ## Pricing 1NCE Plugins allow you to start at no cost. Azure Integration plugin by Tartabit provides a 1 month free trial plan. To continue with more features and benefits, please visit the Azure Marketplace and select the right [plan](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/tartabitllc1600893492587.tartabit-iot-bridge?tab=PlansAndPrice) for your business. ## Start Using To start using the 1NCE OS Plugin with Tartabit IoT Bridge you first need to create the service in Tartabit side. For that, please refer to [HTTP Connector](https://docs.tartabit.com/en/Topics/HTTP-Connector). Starting from the main page of Tartabit IoT Bridge, choose _List_ under _Services_ in the left menu, then _New Service_ and finally complete the form for a **HTTP Connector** Service Model. Only Service name, key and model are required. **Keep the Webhook Secret because it is necessary for creating the plugin in 1NCE OS system**. To finish the configuration in 1NCE OS you can choose one of the two options described below. :::warning Please note that by installing this plugin, you are aware that **Data from any device is shared with Tartabit, regardless of whether it is configured on Tartabit or not**. ::: # Tartabit Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Tartabit".
![Tartabit Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/Plugins-new-icon.png)
To install a Tartabit Plugin you should provide both Webhook Secret and the Server Domain from Tartabit.
![Tartabit plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/plugins-new-installation.png)
# Tartabit plugin installation via API ## Plugin Installation The Tartabit plugin can be created via the `partners` API by using "TARTABIT" partner in the [API Explorer](/api/). Both the Webhook Secret and the Server Domain from Tartabit should be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/TARTABIT/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "serverDomain": "bridge-us.tartabit.com", "webhookKey": "secretKey" }' ``` ## Plugin failure event There is possibility that data forwarding from the 1NCEOS to the Tartabit system can fail due to misconfiguration or temporary downtime. In that case you will see following `Error` Admin Log:
![Plugin Disabled Admin Log](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/plugin-admin-log.png)
You can use similar approach to the [Cloud Integrations failure monitoring](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event#cloud-integrations-failure-monitoring) , only for Plugins Cloud Integrator `Error` event will be following: ```json { "received": "1762419188874", "id": "1-690c61f4-e57d85442c1fee9340783e17", "type": "ERROR", "error": { "payloadExists": false, "description": "One of your plugins has failed. Please check the plugins section of 1NCE OS", "id": "3568Vyh2vh2uCIcFrrMyv6xRoIf", "type": "INTEGRATION", "message": "CloudIntegrator[PluginDisabled]" }, "version": "1.0.0" } ``` In such cases you should investigate if Tartabit system is working fine and if everything is fine trigger plugin Restart using [Restart a failed plugin by installation ID](/api/1nce-os/restart-a-failed-plugin-by-installation-id/) API endpoint or in the Frontend Tartabit plugin details page. ## Integration Restart, Get or Uninstall endpoints To restart, get, or uninstall your Tartabit integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Outcome of successful configuration ## Services List If the configuration is successful, events should appear in the Tartabit services list history.
![Services List](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/tartabit-services.png)
## Event viewer All event details can be found under Triggers/Event Viewer.
![Event viewer](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/tartabit-event-viewer.png)
--- # Data Visualization Plugin by Datacake Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/ ## Description Elevate your IoT experience with the Datacake Plugin, a one-click solution that effortlessly connects the Datacake IoT platform with 1NCE OS. This intuitive plugin automatically lists devices operating on 1NCE OS within Datacake, streamlining device management. Adding a device is as simple as a click, unlocking a suite of features including pre-set dashboards for real-time monitoring and analysis. Designed for efficiency and ease of use, the Datacake Plugin is the ideal tool for enhancing your IoT ecosystem. ## Pricing 1NCE Plugins allow you to start at no cost. Data Visualization plugin by Datacake comes with a free trial plan for up to 5 devices. You can increase the number of devices and unlock more features and benefits by selecting the right [plan](https://datacake.co/pricing) for your business. ## Start Using To start using the 1NCE OS Plugin with Datacake you first need to Add a Device on the Datacake side. For that, please refer to [1NCE OS in Datacake](https://docs.datacake.de/integrations/1nce-os). Starting from the main page of Datacake, choose _+ Add Device_ under _Devices_ in the left menu, then _Connect 1NCE Devices_. **Keep the Workspace ID because it is necessary for creating the plugin in 1NCE OS system**.
![1NCE in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake.png)
![Workspace ID in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/Datacake-workspace-id.png)
To finish the configuration in 1NCE OS you can choose one of the two options described below. After configuration is done for 1NCE OS and data flow is enabled devices should be automatically available on datacake to be configured. :::warning Please note that by installing this plugin, you are aware that **Data from any device is shared with Datacake, regardless of whether it is configured on Datacake or not**. ::: # Datacake Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Datacake".
![Datacake Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-plugin.png)
To install a Datacake Plugin you should provide the Workspace Id from Datacake.
![Datacake plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-plugin-configuration.png)
# Datacake plugin installation via API ## Plugin Installation The Datacake plugin can be created via `partners` API by using "DATACAKE" partner in the [API Explorer](/api/). Only workspaceId from Datacake should be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/DATACAKE/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "workspaceId": "00000000-0000-0000-0000-000000000000" }' ``` ## Plugin failure event There is possibility that data forwarding from the 1NCEOS to the Datacake system can fail due to misconfiguration or temporary downtime. In that case you will see following `Error` Admin Log:
![Plugin Disabled Admin Log](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/plugin-admin-log.png)
You can use similar approach to the [Cloud Integrations failure monitoring](/docs/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event#cloud-integrations-failure-monitoring) , only for Plugins Cloud Integrator `Error` event will be following: ```json { "received": "1762419188874", "id": "1-690c61f4-e57d85442c1fee9340783e17", "type": "ERROR", "error": { "payloadExists": false, "description": "One of your plugins has failed. Please check the plugins section of 1NCE OS", "id": "3568Vyh2vh2uCIcFrrMyv6xRoIf", "type": "INTEGRATION", "message": "CloudIntegrator[PluginDisabled]" }, "version": "1.0.0" } ``` ## Integration Restart, Get or Uninstall endpoints To restart, get, or uninstall your Datacake integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Outcome of successful configuration If the configuration is completed in Datacake dashboards for the device fleet can be created for data visualization.
![Device fleet in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-data-fleet.png)
![Datacake dashaboard](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/Datacake-dashboards.png)

Datacake dashboard

--- # Device Observability Plugin by Memfault Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/ ## Description Memfault provides observability purpose-built for devices. Compatible with constrained microcontroller-based devices to complex Linux and Android systems, Memfault helps embedded development teams understand exactly how their devices perform in the field, and find and fix faults fast. **Fault Diagnostics**: Automatically capture diagnostics data every time your devices experience a crash or unexpected error. Diagnose and debug faults happening in the field within hours, not days or weeks.\ **Log Management**: Automatic log storage, collection, and analysis designed for devices, not servers and apps. Save hours with every investigation and turn your logs into a tool for fleet-wide insights.\ **Fleet Health Monitoring**: Monitor the health of your fleet in real-time with built-in tools for comparison between software versions, hardware versions, and more. We handle the data collection and processing, you get the insights.\ **Product Analytics**: Understand product usage, performance, and reliability using real-world data. Collect product usage data from every device in your fleet even when they aren’t connected so there are no gaps in your data and no more guessing. ## Pricing 1NCE OS Plugins allow you to start at no cost. The Device Observability plugin by Memfault has a free trial plan for up to 10 devices. You can increase the number of devices and unlock more features and benefits by selecting the right [plan for your business](https://memfault.com/pricing/). ## Start Using To install Plugin in 1NCE OS you can choose one of the two options described below. After configuration is done you can use the [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo) from 1NCE OS to showcase Memfault Plugin features and understand the capabilities of 1NCE OS SDK. :::warning Please note that during Memfault plugin installation your Organization's email address will be used for the new Memfault account. You will need access to this email to receive confirmation email from Memfault after Sign up. Please note that by installing this plugin, you are aware that **data is shared with Memfault**. ::: # Memfault Plugin Installation via Frontend ## Plugin Installation The Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Memfault."
![Memfault Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-tile.png)
There is no need to provide any extra information, so you can immediatelly proceed with the installation by pressing the "Install" button on the "Plugin Details page." :::warning Please note that after pressing install button system automatically creates Memfault account with your 1NCE Organization's email address, which cannot be changed afterwards. :::
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details.png)
If plugin installation goes well you should see the "Plugin Installed" page.\ After this, you already can start sending data to the Memfault system.
![Memfault plugin installed](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-installed.png)
In the Plugin installed page, you will see the "Open Memfault Portal" button, which in the new browser tab will open your new Memfault account finalization page. The email field will be already prefilled with your 1NCE Organization's email address.
![Finalize Memfault account](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/create-memfault-account.jpg)
In case you navigate away from the "Plugin Installed" page you can still get the Memfault registration URL by navigating to the Memfault plugin details and clicking on the "Register with Memfault" link.
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details-unfinished.png)
After registration in the Memfault portal is completed you should see the following plugin details page, where we provide details about the Memfault plugin and the "Memfault portal" link to easily navigate to your Memfault account.\ If you need to uninstall the Memfault plugin it also can be done from this page. The uninstall button will only remove the plugin from the 1NCE system, in the Memfault portal account will not be deleted.
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details-finished.png)
# Memfault plugin installation via API ## Plugin Installation The Memfault plugin can be created via the `partners` API by using the "MEMFAULT" partner in the [API Explorer](/api/).\ There is no need to pass any request body during the POST request. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MEMFAULT/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ ``` ## Plugin Get and Uninstall endpoints To get details or uninstall your Memfault integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). :::warning Memfault portal Url to finalize registration can be retrieved only in the response of the Get Plugin Details endpoint. ::: # Utilizing Memfault plugin The Memfault server receives and stores debug and log data sent by your devices. 1NCE OS Memfault plugin supports CoAP/CoAPs to HTTPS proxying with seamless support for Authorization. All the data sent by the device to the 1NCE OS Coap Proxy server is proxied to the Memfault [Chunks endpoint](https://api-docs.memfault.com/#a8d3e36f-62f0-4120-9fc6-544ee04f3bb5). We automatically pass device ICCID as a device identifier to the Memfault system, so the following URI should be added in CoAP Requests `Proxy-URI`option: ``` https://chunks.memfault.com/api/v0/chunks/:iccid: ``` Additionally please remember to set the correct `Content-Format` option, for binary payloads it should be 42. To utilize proxy functionality please use one of the following endpoints for CoAP requests: * `coap://coap.proxy.os.1nce.com:5683` * `coaps://coaps.proxy.os.1nce.com:5684`. *If CoAPs is required to be used please refer to[DTLS encryption for CoAP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap#dtls-encryption-for-coap).* ### Coap to HTTPS Proxy functionality CoAP to HTTPS proxy's main functionality is to "translate" the CoAP requests to HTTPS requests and HTTPS responses to CoAP responses. As mentioned before 1NCE OS Coap Proxy for Memfault Plugin automatically replaces `:iccid:` part with the actual ICCID value before doing HTTPS request to the Memfault chunks API.\ Additionally, the Memfault plugin also retrieves and stores the Memfault project key value during plugin installation. This value then is automatically injected as a `Memfault-Project-Key` header into the HTTPS request towards Memfault Chunks API endpoint, so there is no need to manage it from the customer device side. ## Adding devices in Memfault After Memfault plugin installation is done you can utilize [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo) to start sending chunks data to the Memfault system. If chunks are processed successfully, the device will show up in the Memfault portal on the Devices page automatically with the ICCID of the 1NCE sim card used as a device serial number.
![Memfault Devices](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-device-page.png)
# Features and Limitations General [Plugins features and limitations](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations) applies to Memfault.\ There are still some individual Features and Limitations applied to the Memfault plugin: ## Features * Seamless Memfault plugin creation without the need to prepare or enter any additional information. * Automatic Memfault authorization process in the Coap Proxy without the need to store any secrets or extra configuration on the device. ## Limitations * During Memfault account creation system will use your 1NCE Organization's email address, so there is no way to provide a custom email before plugin installation. * The device serial number in the Memfault system always is the ICCID of the 1NCE sim card. * Maximum supported payload size for Coap Proxy requests is 5120 bytes. It is suggested to send payload which is smaller than 1024 bytes in a single request to not trigger block-wise transfer. * Currently only supported Memfault proxying mode is uploading a single chunk in one request, other modes like base64-encoded chunks and multiple chunks in one request described in the [Memfault Chunks endpoint](https://api-docs.memfault.com/#a8d3e36f-62f0-4120-9fc6-544ee04f3bb5) are not supported. # Outcome of successful plugin creation After devices start to send data to the Memfault system, you can start monitoring different aspects of your device fleet.\ The Connectivity page provides useful insights like device uptime, sent data amount, and more.
![Memfault Connectivity](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-connectivity-page.png)
On the Overview page, you can display many different useful widgets.
![Memfault Overview](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-main-page.png)
More information about how to use Memfault features can be found in the [Memfault Documentation](https://docs.memfault.com/docs/platform/introduction). --- # Features & Limitations Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations/ # Features * All [Event Types](/docs/1nce-os/1nce-os-cloud-integrator/#event-types) from 1NCE OS will be forwarded to Plugins.\ *Doesn't apply for Mender and Memfault plugin* * [Event Types](/docs/1nce-os/1nce-os-cloud-integrator/#event-types) messages will be forwarded in JSON format.\ *Doesn't apply for Mender and Memfault plugin* # Limitations * The plugin cannot be edited. It should be reinstalled if any changes are required. * Only one entity per Plugin type is allowed to be created. --- # FOTA Management Plugin by Mender Source: https://help.1nce.com/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/ ## Description Continuously roll out new firmware to ensure compliance with security regulations like the EU Cyber Resilience Act while improving your customer experience with stability enhancements and new innovative features. Mender is the market-leading FOTA Management solution, providing secure and robust over-the-air (OTA) software updates for your entire device fleet. **Security by design**: Ensure communication, data integrity, and authenticity are verified. Trust a battle-tested solution with millions of devices under management.\ **Robustness**: Minimize the risk of bricking devices, even in cases of losing power or connectivity in the middle of the update process. Devices will always be in a known and operable state\ **Optimize**: Meet bandwidth and uptime requirements and realize up to a 90% reduction in bandwidth consumption with delta updates. Advanced scheduling and phased rollout to minimize risk of fleet interruption. ## Pricing 1NCE Plugins allow you to start at no cost. Firmware Over-The-Air Management plugin by Mender comes with a free trial plan for up to 10 devices for 12 months. You can increase the number of devices and unlock more features and benefits by selecting the right [plan](https://mender.io/product/pricing) for your business. For further inquiries about usage and pricing, please reach out to [contact@mender.io](mailto:contact@mender.io). ## Start Using To start using the 1NCE OS Plugin with Mender you first need to create a hosted Mender account and get an Organization token on the Mender side. Starting from the main page of Mender, choose *My organization* under the dropdown on your profile. **Keep the Organization token because it is necessary for creating the plugin in the 1NCE OS system**.
![Organization Token in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-Organization-Token.png)
To finish the configuration in 1NCE OS you can choose one of the two options described below. After configuration is done you can use the [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo) from 1NCE OS to showcase Mender Plugin features and understand the capabilities of 1NCE OS SDK & FOTA client. :::warning Please note that by installing this plugin, you are aware that **data is shared with Mender**. ::: # Mender Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Mender".
![Mender Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-plugin.png)
To install a Mender Plugin you should provide the Organization Token from Mender.
![Mender plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-plugin-configuration.png)
# Mender plugin installation via API ## Plugin Installation The Mender plugin can be created via the `partners` API by using the "MENDER" partner in the [API Explorer](/api/).\ Only the `Organization token` from the Mender is mandatory to be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MENDER/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "tenantToken": "abcdef123456" }' ``` If a specific user-generated Private Key and Public Key requires to be added it can be done only via API. ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MENDER/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "tenantToken": "abcdef123456", "publicKey": "-----BEGIN PUBLIC KEY-----\n .. \n-----END PUBLIC KEY-----\n", "privateKey": "-----BEGIN PRIVATE KEY-----\n .. \n-----END PRIVATE KEY-----\n" }' ``` ## Integration Get or Uninstall endpoints To get details or uninstall your Mender integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Utilizing Mender plugin The Mender server stores and controls the deployment of software updates over the air to your devices. Mender can be used to manage devices, upload and manage software releases to the server, and create deployments to roll out software to your devices. 1NCE OS mender plugin supports CoAP/CoAPs to HTTPS proxying with seamless support for Authorization. The HTTPs [Mender endpoints](https://docs.mender.io/api/#device-apis) should be added in CoAP Requests Proxy-URI options. To utilize proxy functionality please use one of the following endpoints for CoAP requests: * `coap://coap.proxy.os.1nce.com:5683/mender` * `coaps://coaps.proxy.os.1nce.com:5684/mender`.\ *If CoAPs is required to be used please refer to[DTLS encryption for CoAP](/docs/1nce-os/1nce-os-device-integrator/device-integrator-coap#dtls-encryption-for-coap).* ### Coap to HTTPS Proxy functionality CoAP to HTTPS proxy's main functionality is to "translate" the CoAP requests to HTTPS requests and HTTPS responses to CoAP responses. Mender Plugin provides additional logic for [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) and ensures Authorization header injection for other Mender endpoints. * Whenever [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) is used for POST requests, 1NCE OS will generate the correct request body required for authentication and store the returned JWT token in the system for future use. **Please note that renewing the JWT token requires calling the endpoint once again**. Post request body example: ``` { "id_data": "{\"iccid\":\"1234567890123456789\"}", "pubKey": "-----BEGIN PUBLIC KEY-----\n .. \n-----END PUBLIC KEY-----\n", "tenant_token": "abcdef123456=" } ``` * For any other request where [Mender endpoints](https://docs.mender.io/api/#device-apis) are being used in Proxy-URI options, the JWT token will be added as an additional Authorization header for HTTPS request. ``` { "Authorization": "Bearer 'JWT_TOKEN'" } ``` * If [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) was never called and JWT token is not present in 1NCE OS, then the request will be proxied without the Authorization header. ## Adding devices in Mender By proxying the POST request to [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) device would show up in mender as "Pending". The device needs to be accepted by selecting "Accept device".
![Pending Device in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-Device-Pending.png)
![Accepting Device in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-device-acceptance2.png)
## Release, Deployment creation To use the 1NCE OS Plugin for Release and deployment management in Mender, please refer to [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo) from 1NCE OS. Examples of Artifact creation, Release, and Deployment management are provided. # Features and Limitations General [Plugins features and limitations](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations) applies to Mender. There are still some individual Limitations applied for Mender: ## Limitations * Only mender endpoints are allowed to be proxied. The following endpoints in CoAP Request Proxy-URI options are allowed for Mender Plugin:\ `hosted.mender.io`\ `eu.hosted.mender.io` * Public key and Private key can be provided only via API. Keys should be a pair and they should be provided in `PEM` format. The public key max allowed string length is 1000 chars, Private key max allowed string length is 3000 chars. * Currently only `RSA PKCS1` and `RSA PKCS8` private and public key types are supported. Other types `ECDSA` and `ED25519` are not supported for now. # Outcome of successful configuration ## Device List If the configuration is completed devices should be accepted and available on the Mender devices list.
![Device fleet in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-device.png)
## Deployment status In the case of an active deployment, it should be possible to track deployment statuses such as 'downloading,' 'installing,' 'success,' and other relevant [statuses](https://docs.mender.io/api/#management-api-deployments-list-all-devices-in-deployment-responses).
![Deployment with status 'installing'](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Installing.png)
In device deployment history it should be available to see all deployments.
![Device deployment history](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Deployment-log.png)
--- # 1NCE SDK & Blueprints Source: https://help.1nce.com/docs/1nce-os/1nce-os-sdk-blueprints/
![](/img/1nce-os/1nce-os-sdk-blueprints/001.png)
1NCE offers different Blueprints and SDKs to allow customers a seamless setup and use of all features as part of 1NCE OS. ## 1NCE SDK The 1NCE SDK is an open-source, MIT-licensed, C SDK which can be integrated into the customer IoT devices firmware. It contains functions to authenticate against the 1NCE OS managed cloud service and to compress data for use with Energy Saver.\ The 1NCE SDK can be downloaded at: [https://github.com/1NCE-GmbH/1nce-iot-c-sdk](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) ## Blueprints Blueprints are open-source, MIT-licensed code repositories for embedded platforms. We offer onboarding scripts like the FreeRTOS onboarding blueprint to guide through all our features that 1NCE OS offers. With examples and code, we hope to make the setup smooth and simple. * [FreeRTOS Blueprint](/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos) * [Zephyr Blueprint](/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr) * [Arduino Blueprint](/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-arduino) --- # Arduino Blueprint Source: https://help.1nce.com/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-arduino/ # 1NCE Arduino Blueprint ## Overview 1NCE Arduino blueprint provides an overview of various features of 1NCE OS including Device Authenticator, IoT Integrator and Energy Saver. In combination with 1NCE SDK. ## Supported Boards The Blueprint is compatible with [Arduino Portenta H7](https://docs.arduino.cc/hardware/portenta-h7) and [Arduino Portenta H7 lite ](https://docs.arduino.cc/hardware/portenta-h7-lite) (running Mbed OS), attached to [Portenta Cat. M1/NB IoT GNSS Shield](https://docs.arduino.cc/hardware/portenta-cat-m1-nb-iot-gnss-shield). ## 1NCE IoT C SDK Integration [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) is a collection of C source files that can be used to connect and benefit from different services from 1NCE OS. The SDK is integrated with the blueprint through UDP & Log interfaces. ## 1NCE Arduino blueprint - UDP Demo ### Overview 1NCE Arduino UDP Demo allows customers to communicate with 1NCE endpoints via UDP Protocol, and it can send compressed payload using the Energy Saver feature. ### Using 1NCE Energy saver The demo can send optimized payload using 1NCE Energy saver. This feature is enabled by default with the following definition in `nce_demo_config.h` ``` #define ENABLE_NCE_ENERGY_SAVER ``` The energy saver template used in the demo can be found in `extras/template.json` ### Configuration options The configuration options for UDP sample are: `NCE_UDP_ENDPOINT` is set to 1NCE endpoint. `NCE_UDP_PORT` is set by default to the 1NCE UDP endpoint port 4445. `NCE_UDP_DATA_UPLOAD_FREQUENCY_SECONDS` the interval between UDP packets. `NCE_PAYLOAD` Message to send to 1NCE IoT Integrator. `NCE_PAYLOAD_DATA_SIZE` Used when 1NCE Energy Saver is enabled to define the payload data size of the translation template. ## 1NCE Arduino blueprint - CoAP Demo ### Overview 1NCE Arduino CoAP Demo allows customers to establish a secure communication with 1NCE endpoints via CoAPs after receiving DTLS credentials from Device Authenticator using the SDK. It can also send compressed payload using the Energy Saver feature. ### Secure Communication with DTLS using 1NCE SDK By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. ### Using 1NCE Energy saver The demo can send optimized payload using 1NCE Energy saver. This feature is enabled by default with the following definition in `nce_demo_config.h` ``` #define ENABLE_NCE_ENERGY_SAVER ``` The energy saver template used in the demo can be found in `extras/template.json` ### Unsecure CoAP Communication To test unsecure communication, disable the device authenticator by removing the following definition from `nce_demo_config.h` ``` #define ENABLE_NCE_DEVICE_AUTHENTICATOR ``` ### Configuration options The configuration options for CoAP sample are: `NCE_COAP_ENDPOINT` is set to 1NCE endpoint. `NCE_COAP_PORT` is set automatically based on security options (with/without DTLS). `NCE_COAP_URI_QUERY` the URI Query option used to set the MQTT topic for 1NCE IoT integrator. `NCE_COAP_DATA_UPLOAD_FREQUENCY_SECONDS` the interval between CoAP packets. `NCE_PAYLOAD` Message to send to 1NCE IoT Integrator. `NCE_PAYLOAD_DATA_SIZE` Used when 1NCE Energy Saver is enabled to define the payload data size of the translation template. ## 1NCE Arduino blueprint - LwM2M Demo ### Overview 1NCE Arduino LwM2M Demo allows customers to communicate with 1NCE endpoints via LwM2M Protocol. LwM2M Actions can be tested using the [Action API](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/). For example: * To get the firmare update object info, send a `read` action to object `/5`. ### Configuration options The configuration options for LwM2M sample are: `NCE_ICCID` the ICCID of 1NCE SIM Card. `LWM2M_ENDPOINT` is set to 1NCE endpoint. DTLS is enabled by default. To use DTLS, bootstraping PSK should be defined in `LWM2M_BOOTSTRAP_PSK`. It can be configured while testing the LwM2M integration (From the Device integrator), or from the API [Create Pre-Shared Device Key](/api/1nce-os/create-pre-shared-device-key/). ### Unsecure LwM2M Communication To test unsecure communication, disable the device authenticator by removing the following definition from `nce_demo_config.h` ``` #define LwM2M_ENABLE_DTLS ``` --- # FreeRTOS Blueprint Source: https://help.1nce.com/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/ 1NCE FreeRTOS BluePrint demonstrates the usage of various IoT protocols inculuding CoAP, LwM2M, and UDP with cellular connectivity. In combination with 1NCE SDK for the integration of 1NCE OS tools. # Overview 1NCE FreeRTOS BluePrint release integrates 1NCE SDK to benefit from different 1NCE OS tools including device Authentication and Energy Saver, with the addition of a static library for CoAP Protocol ([Lobaro CoAP](https://www.lobaro.com/portfolio/lobaro-coap/)) and LwM2M ([Wakaama](https://www.eclipse.org/wakaama/)). This Repository present examples of simple code: * CoAP protocol * CoAPs protocol (with DTLS security using Pre-shared key) * UDP Demo * LwM2M with Bootstrap * LwM2M without Bootstrap Additionally, All the Demos have the Energy Saver feature as a Flag that can be enabled to test this feature. # Getting started ## Prerequisites * B-L475E-IOT01A2 STM32 Discovery kit IoT node connected to BG96 (LTE Cat M1/Cat NB1/EGPRS modem) through X-NUCLEO-STMODA1 expansion board. * [1NCE SIM Card.](https://shop.1nce.com/portal/shop/) * STM32CubeIDE from [https://www.st.com/content/st\_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-ides/stm32cubeide.html](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-ides/stm32cubeide.html) * STM32 ST-LINK utility from [https://www.st.com/en/development-tools/stsw-link004.html](https://www.st.com/en/development-tools/stsw-link004.html) * Upgrade the modem BG96 to the latest firmware. ([https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem\_FW](https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW))\ **Note:** Download the modem FW flasher tool (QFlash) from this url: [https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem\_FW](https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW) this tools taked from quectel from the web site listed in the official documentation. ## Cloning the Repository After navigating to your workspace Clone the repository using HTTPS\: ``` $ git clone https://github.com/1NCE-GmbH/blueprint-freertos.git --recurse-submodules ``` Using SSH: ``` $ git clone git@github.com:1NCE-GmbH/blueprint-freertos.git --recurse-submodules ``` If you have downloaded the repo without using the --recurse-submodules argument, you need to run: ``` git submodule update --init --recursive ``` * Import the project in STM32Cube. ## Building Sample Setup your demo want to use by going to config\_files/aws\_demo\_config.h define one of three demos exist (by default `CONFIG_COAP_DEMO_ENABLED`) ``` CONFIG_COAP_DEMO_ENABLED CONFIG_UDP_DEMO_ENABLED CONFIG_LwM2M_DEMO_ENABLED ``` ## Sample Demos ### COAP Demo without DTLS 1NCE FreeRTOS BluePrint allows customers to communicate with 1NCE endpoints via CoAP and use of all features as part of the 1NCE OS. COAP POST request:\ In this Section, the following steps are executed: * Register to the Network. * Perform a DNS Resolution. * Create a socket and connect to Server * Create Confirmable CoAP POST with Query option * Create Client Interaction and analyze the response (ACK) * Validate the response. * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_COAP_DEMO_ENABLED ``` * The onboarding script configuration can be found in blueprint-freertos\\vendors\\st\\boards\\stm32l475\_discovery\\aws\_demos\\config\_files\\nce\_demo\_config.h in the root folder of the blueprint or /aws\_demos/config\_files/nce\_demo\_config.h in IDE. ``` #define PUBLISH_PAYLOAD_FORMAT "Welcome to 1NCE's Solution" #define democonfigCLIENT_ICCID "" #define COAP_ENDPOINT "coap.os.1nce.com" #define configCOAP_PORT 5683 #define democonfigCLIENT_IDENTIFIER "t=test" #if ( configCOAP_PORT == 5684 ) #define ENABLE_DTLS #endif /* Enable send the Information to 1NCE's client support */ #if defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 ) #ifndef ENABLE_DTLS #define ENABLE_DTLS #endif #endif ``` ### CoAPs with DTLS For the DTLS Support the default Port is 5684 and automatically defines the `ENABLE_DTLS` as an additional define The CoAP DTLS performs 3 main tasks from the [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) : * Send the Device Authenticator Request * Get the Response * Process the Response and give the DTLS identity and PSK to the application code. ### UDP Demo 1NCE FreeRTOS Blueprint allows customers to communicate with 1NCE endpoints via UDP and use all features as part of the 1NCE OS. * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_UDP_DEMO_ENABLED ``` * The onboarding script configuration can be found in blueprint-freertos\\vendors\\st\\boards\\stm32l475\_discovery\\aws\_demos\\config\_files\\nce\_demo\_config.h in the root folder of the blueprint or /aws\_demos/config\_files/nce\_demo\_config.h in IDE. ``` #define UDP_ENDPOINT "udp.os.1nce.com" #define UDP_PORT 4445 #define CONFIG_NCE_ENERGY_SAVER //the message you want to publish in IoT Core #define PUBLISH_PAYLOAD_FORMAT "Welcome to 1NCE's Solution" #define democonfigCLIENT_ICCID "" ``` ### LwM2M Demo The LWM2M support is provided using Eclipse Wakaama library communicating with a Leshan LWM2M server * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_LwM2M_DEMO_ENABLED ``` * The client that has registered on the LwM2M server, can send data by doing the Send operation. More specifically, it is used by the Client to report values for Resources and Resource Instances of known LwM2M Object Instance(s) to the LwM2M Server.\ To use this feature in our Blueprint: remove/ comment #define LWM2M\_PASSIVE\_REPORTING and define sending object (e.g. /4/0 here). The LWM2M endpoint and the client name can be configured in config\_files/nce\_demo\_config.h as follows: ``` #define LWM2M_ENDPOINT "lwm2m.os.1nce.com" #define ENABLE_DTLS #define LWM2M_CLIENT_MODE #define LWM2M_BOOTSTRAP #ifdef ENABLE_DTLS char lwm2m_psk[30]; char lwm2m_psk_id[30]; #endif #define LWM2M_SUPPORT_SENML_JSON #define LWM2M_LITTLE_ENDIAN #define LWM2M_SUPPORT_TLV #define LWM2M_COAP_DEFAULT_BLOCK_SIZE 1024 #define LWM2M_VERSION_1_1 #define LWM2M_SINGLE_SERVER_REGISTERATION //#define LWM2M_PASSIVE_REPORTING #if defined(LWM2M_PASSIVE_REPORTING) #define LWM2M_1NCE_LIFETIME 30000 #else #define LWM2M_OBJECT_SEND "/4/0" #endif ``` ## Troubleshooting Demo: > This feature is limited to Users and Accounts who have already accepted our 1NCEOS Addendum to the 1NCE T\&Cs. It is a one-time action per 1NCE Customer Account. Please log into the 1NCE Customer Portal as Owner or Admin, navigate to the 1NCEOS, and accept the Terms. If you don't see anything to accept and get directly to the Dashboard of the 1NCEOS, you are ready to go! > > N.B: The SMS and Data Consumed for the Troubleshooting are counted against the Customers own Volume of the SIM Card. This initial version's main target is to allow customers to connect their Things and automate the network debugging faster and more reliably. This will also reduce the workload on our Customer facing support teams and will also allow us to focus on further common issues. * Go to config\_files/nce\_demo\_config.h --> enable the flag TROUBLESHOOTING (Troubleshooting Example with/without DTLS in primary Flow and SMS as an alternative) ``` #define COAP_ENDPOINT "coap.os.1nce.com" #define configCOAP_PORT 5684 #define democonfigCLIENT_IDENTIFIER "t=test" #if ( configCOAP_PORT == 5684 ) #define ENABLE_DTLS #endif /* Enable send the Information to 1NCE's client support */ #define TROUBLESHOOTING #if defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 ) #ifndef ENABLE_DTLS #define ENABLE_DTLS #endif #endif ``` * run the demo : the demo will send the information to the coap endpoint as a first step if No ACK comes then an SMS to 1NCE portal with the required pieces of information. ## Primary Case ![Troubleshooting from the coap endpoint](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/fd91e61-troubleshootingcoap.png) ## Fallback ![Troubleshooting from Portal](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/ddf7711-troubleshootingcoap2.png) for more information on the troubleshooting | Parameter | Description | | --- | --- | | Radio Access Technology | * GSM * LTE * CATM1 * NBIOT * Otherwise: NULL | | Public Land Mobile Network (PLMN) information | * Mobile Country Code * Mobile Network Code | | Registered Network (RN) | * Registered network operator cell Id. * Registered network operator Location Area Code. * Registered network operator Routing Area Code. * Registered network operator Tracking Area Code. | | Reject CS ((Circuit Switched) registration status) | * : Table 2. * : 0: 3GPP specific Reject Cause. Manufacture specific. : Circuit Switch Reject cause. | | Reject PS ((Packet Switched) registration status) | * : Table 2. * : 0: 3GPP specific Reject Cause. Manufacture specific. : Circuit Switch Reject cause. | | Signal Information | * Received Signal Strength Indicator (RSSI) in dBm. * LTE Reference Signal Received Power (RSRP) in dBm * LTE Reference Signal Received Quality (RSRQ) in dB. * LTE Signal to Interference-Noise Ratio in dB. * Bit Error Rate (BER) in 0.01%. * A number between 0 to 5 (both inclusive) indicating signal strength. |

Table 1. Key Feature of Troubleshooting Message

| Number | description | | :----: | :---------------------------------------------------------------- | | 0 | CELLULAR NETWORK REGISTRATION STATUS NOT REGISTERED NOT SEARCHING | | 1 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED HOME | | 2 | CELLULAR NETWORK REGISTRATION STATUS NOT REGISTERED SEARCHING | | 3 | CELLULAR NETWORK REGISTRATION STATUS REGISTRATION DENIED | | 4 | CELLULAR NETWORK REGISTRATION STATUS UNKNOWN | | 5 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED ROAMING | | 6 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED HOME SMS ONLY | | 7 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED ROAMING SMS ONLY | | 8 | CELLULAR NETWORK REGISTRATION STATUS ATTACHED EMERG SERVICES ONLY | | 9 | CELLULAR NETWORK REGISTRATION STATUS MAX |

Table 2. Network Registration Status

# Asking for Help The most effective communication with our team is through GitHub. Simply create a [new issue](https://github.com/1NCE-GmbH/blueprint-freertos/issues/new/choose) and select from a range of templates covering bug reports, feature requests, documentation issue, or Gerneral Question. --- # Zephyr Blueprint Source: https://help.1nce.com/docs/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/ # 1NCE Zephyr blueprint ## 🧭 Overview The **1NCE Zephyr Blueprint** is a reference application that showcases how to integrate and use various 1NCE OS features with [Zephyr RTOS](https://zephyrproject.org/), including: * ✅ **Device Authenticator** * 📡 **IoT Integrator** * 🔋 **Energy Saver** * 📥 **Device Controller** for UDP and CoAP-based downlink and real-time remote interaction * 🧩 **Plugin Integrations** with partners like [Mender](https://mender.io) for FOTA and [Memfault](https://memfault.com) for device observability It is based on the **1NCE IoT C SDK** and runs on Nordic Semiconductor boards. The Zephyr OS is a scalable, secure, real-time operating system designed for resource-constrained embedded devices — from smart sensors to full-featured gateways. *** ## 🧱 Supported Boards The demo supports the following Nordic boards: * [nRF9151 Development Kit](https://www.nordicsemi.com/Products/Development-hardware/nrf9151-dk) * [nRF9160 Development Kit](https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk) * [Thingy:91](https://www.nordicsemi.com/Products/Development-hardware/Nordic-Thingy-91) *** ## 🚀 Getting Started This guide walks you through: * Setting up the **1NCE IoT C SDK** * Getting the source code * Building and flashing the blueprint demo *** ### 📦 Prerequisites * [nRF Connect SDK v2.8.0](https://docs.nordicsemi.com/bundle/ncs-2.8.0/page/nrf/installation/install_ncs.html) * [Visual Studio Code](https://code.visualstudio.com/) * [West tool](https://docs.zephyrproject.org/3.1.0/develop/west/install.html) *** ## 🧩 Integrating 1NCE IoT C SDK The [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) provides C-based modules to easily use 1NCE OS services. Follow these steps: 1. **Open`west.yml`:** ```bash %HOMEPATH%\ncs\v2.8.0\nrf\west.yml ``` 2. **Add the module to`name-allowlist`:**\ Ensure `nce-sdk` is listed in alphabetical order. 3. **Activate the SDK via submanifest:** Rename and edit the file: ```bash %HOMEPATH%\ncs\v2.8.0\zephyr\submanifests\example.yaml ``` ```yaml manifest: projects: - name: nce-sdk url: https://github.com/1NCE-GmbH/1nce-iot-c-sdk revision: main ``` 4. **Run West update:**\ Open a terminal (e.g., `cmd.exe` on Windows, Terminal on macOS/Linux) and run: ```bash cd %HOMEPATH%\ncs\v2.8.0 west update ``` *** ## ▶️ Running the Demo 1. **Clone the Blueprint Repository:** ```bash git clone https://github.com/1NCE-GmbH/blueprint-zephyr.git ``` 2. **Open VS Code and Launch nRF Connect Extension** 3. **Add the project:** * Click **Add Existing Application** * Choose the folder where the blueprint was cloned 4. **Create a Build Configuration:** * Select your board target, e.g.: * `nrf9160dk/nrf9160/ns` * `nrf9151dk/nrf9151/ns` * `thingy91/nrf9160/ns` 5. **Flash the board:** * Connect your board via USB * Click **Flash** or **Debug** to deploy the firmware 📖 Need help with board connection?\ 👉 [Nordic Docs: Connect Using Serial Port](https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/guides/bd_work_with_boards.html#how-to-connect-using-serial-port) *** ## 🧪 Testing Instructions for Thingy:91 To easily test the default setup on the **Thingy:91**, follow these steps using the provided binaries for the specific demo you'd like to run: 1. **Remove the plastic cover** from the Thingy:91. 2. **Connect the device to your computer** using a micro-USB cable. 3. **Enter DFU mode**: * Power off the Thingy:91. * Hold down the **black button** while switching the power back to **ON**. 4. **Open[nRF Connect for Desktop](https://www.nordicsemi.com/Products/Development-tools/nrf-connect-for-desktop)** and launch the **Programmer** tool. 5. Click **SELECT DEVICE** and choose **Thingy:91** from the dropdown list. 6. In the left panel, go to **File > Add file > Browse** and choose the appropriate `.hex` file from the `thingy_binaries` folder of your desired demo. 7. Scroll down to **Enable MCUboot** and ensure it is checked. 8. Click **Write** on the left panel, then confirm again in the **MCUboot DFU** pop-up by pressing **Write**. 9. Wait for the update to finish. A message saying **"Completed successfully"** will confirm a successful flash. ### 📂 Available Firmware for Thingy:91 * [🔐 CoAP Demo Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/nce_coap_demo/thingy_binaries) * [📡 UDP Demo Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/nce_udp_demo/thingy_binaries) * [📥 FOTA with Mender Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo/thingy_binaries) * [🛠️ Debug with Memfault Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo/thingy_binaries) :::tip For Memfault diagnostics and debugging, you should upload [zephyr.elf](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_debug_memfault_demo/thingy_binaries/zephyr.elf) file to the Memfault portal. Refer to the [Memfault documentation](https://docs.memfault.com) for instructions on setting up symbol files and debugging integration.\ For a faster getting started experience, you can directly use the documentation under [`plugin_system/nce_debug_memfault_demo`](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo). ::: 📘 For more detailed device guidance, check the official [Thingy:91 Getting Started Guide](https://docs.nordicsemi.com/bundle/ncs-2.6.1/page/nrf/device_guides/working_with_nrf/nrf91/thingy91_gsg.html) *** ## 📚 Demos in This Blueprint The blueprint includes the following applications: | Demo Path | Summary | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `nce_coap_demo` | Secure CoAP communication using DTLS from Device Authenticator, with Energy Saver & Device Controller support | | `nce_udp_demo` | Lightweight UDP communication with compressed payloads and Device Controller | | `nce_lwm2m_demo` | LwM2M client for LED, buzzer, and sensor control over CoAP/DTLS with support for 1NCE Action API | | `plugin_system/nce_debug_memfault_demo` | Device diagnostics and crash reporting using Memfault over the 1NCE CoAP Proxy | | `plugin_system/nce_fota_mender_demo` | Firmware-over-the-air updates via Mender.io using the 1NCE CoAP Proxy and secure onboarding | *** # Sample Demos # 1NCE Zephyr blueprint - UDP Demo ## Overview 1NCE Zephyr UDP Demo allows customers to communicate with 1NCE endpoints via UDP Protocol, and it can send compressed payload using the Energy Saver feature. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – Connecting to the network * 🔵 **BLUE** – Network connection established * 🟢 **GREEN** – Message sent to 1NCE OS ## ⚡ Using 1NCE Energy Saver The demo can send optimized payload using 1NCE Energy Saver. To enable this feature, add the following flag to `prj.conf` ``` CONFIG_NCE_ENERGY_SAVER=y ``` When enabled, the device will send compressed messages based on a translation template defined in 1NCE OS portal. :::tip ### **Learn more:** See the [1NCE Energy Saver documentation](/docs/1nce-os/1nce-os-energy-saver) for details on how this feature works and how to configure templates. ::: :::info ### **Tip:** You can view incoming messages in the [Device Inspector](/docs/1nce-os/1nce-os-device-inspector) in the 1NCE OS portal. ::: :::tip Add the template located in `./nce_udp_demo/template/template.json` to the 1NCE OS portal, and enable it for the **UDP protocol** to ensure correct decoding of the compressed payload. ::: ## ⚙️ Configuration Options The available configuration parameters for the UDP demo: | Config Option | Description | Default | | ------------------------------------------ | -------------------------------------------------- | ----------------- | | `CONFIG_UDP_SERVER_HOSTNAME` | UDP server hostname | `udp.os.1nce.com` | | `CONFIG_UDP_SERVER_PORT` | UDP server port number | `4445` | | `CONFIG_UDP_DATA_UPLOAD_FREQUENCY_SECONDS` | Interval between UDP transmissions (in seconds) | `20` | | `CONFIG_UDP_PSM_ENABLE` | Enable LTE Power Saving Mode (PSM) | `n` | | `CONFIG_UDP_EDRX_ENABLE` | Enable LTE enhanced Discontinuous Reception (eDRX) | `n` | | `CONFIG_UDP_RAI_ENABLE` | Enable LTE Release Assistance Indication (RAI) | `n` | *** ### 🔋 Payload Configuration Depending on whether the Energy Saver feature is enabled: * If `CONFIG_NCE_ENERGY_SAVER` is **disabled**: | Config Option | Description | Default | | ---------------- | ----------------------------------- | ----------------------------------------- | | `CONFIG_PAYLOAD` | Message sent to 1NCE IoT Integrator | `{"text": "Hi, this is a test message!"}` | * If `CONFIG_NCE_ENERGY_SAVER` is **enabled**: | Config Option | Description | Default | | ------------------------------ | ----------------------------------------------- | ------- | | `CONFIG_NCE_PAYLOAD_DATA_SIZE` | Payload data size for the Energy Saver template | `10` | ## 🧠 Device Controller The **Device Controller** allows your device to receive CoAP downlink messages using the 1NCE Management API. It supports sending downlink requests that your device can process in real-time. 📘 More info: [1NCE DevHub – Device Controller](/docs/1nce-os/1nce-os-device-controller) ### 🔁 Sending a Request You can trigger a downlink using the following `curl` command: ``` curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices//actions/UDP' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" }' ``` Replace: * `` with your SIM's ICCID * `` with your [OAuth token](/api/authorization/post-access-token-post/) *** ### 📩 Request Parameters | Parameter | Description | Example | | ------------- | -------------------------------------------------------- | ----------------- | | `payload` | Data to send to the device | `"enable_sensor"` | | `payloadType` | Type of payload (`STRING`, `HEX`, etc.) | `"STRING"` | | `port` | UDP port to receive the message (`CONFIG_NCE_RECV_PORT`) | `3000` | | `requestMode` | Request mode (`SEND_NOW` or `SEND_WHEN_ACTIVE`) | `"SEND_NOW"` | *** ## 🔧 Zephyr Device Controller Configuration To enable and handle downlink messages on your device, use the following configs: | Config Option | Description | Default | | ------------------------------------- | ---------------------------------------- | ------- | | `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` | Enables the device controller feature | `y` | | `CONFIG_NCE_RECV_PORT` | UDP port to listen for incoming messages | `3000` | | `CONFIG_NCE_RECEIVE_BUFFER_SIZE` | Buffer size for incoming UDP payloads | `1024` | *** ## 📤 Zephyr Output Example When the Zephyr application receives a UDP downlink from the 1NCE API: ``` [00:00:02.996,978] [downlink_thread] NCE_UDP_DEMO: Downlink thread started... [00:00:02.997,802] [downlink_thread] NCE_UDP_DEMO: Listening on port: 3000 [00:00:11.325,683] [downlink_thread] NCE_UDP_DEMO: Received message: enable_sensor ``` ## 📦 Ready-to-Flash Firmware for Thingy:91 We provide a **prebuilt HEX file** for Thingy:91 that you can flash directly to your device for quick testing.\ No build setup is required — just flash and go. 👉 **Download:** [Thingy:91 Prebuilt HEX](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/nce_udp_demo/thingy_binaries/zephyr.signed.hex) :::warning The firmware is configured with all LTE bands enabled, which may cause a delay of several minutes during the initial network connection while scanning for available bands. This is normal. ::: *** # 1NCE Zephyr blueprint - CoAP Demo ## Overview 1NCE Zephyr CoAP Demo allows customers to establish a secure communication with 1NCE endpoints via CoAPs after receiving DTLS credentials from Device Authenticator using the SDK. It can also send compressed payload using the Energy Saver feature. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – Connecting to the network * 🔵 **BLUE** – Network connection established * 🟢 **GREEN** – Message sent to 1NCE OS ## Secure Communication with DTLS using 1NCE SDK By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. > ⚠️ **Note:** If the Pre-shared Key for DTLS is set manually, **STRING** format should be used. ## Unsecure CoAP Communication To test unsecure communication (plain CoAP), disable the device authenticator by adding the following flag to `prj.conf` ``` CONFIG_NCE_DEVICE_AUTHENTICATOR=n ``` ## ⚡ Using 1NCE Energy saver The demo can send compressed, optimized payloads using 1NCE Energy Saver. This reduces payload size and improves energy efficiency.\ Enable in `prj.conf`: ``` CONFIG_NCE_ENERGY_SAVER=y ``` When enabled, the device will send compressed messages based on a translation template defined in 1NCE OS portal. :::tip Add the template located in `./nce_coap_demo/template/template.json` to the 1NCE OS portal, and enable it for the **COAP protocol** to ensure correct decoding of the compressed payload. ::: :::tip ### **Learn more:** See the [1NCE Energy Saver documentation](/docs/1nce-os/1nce-os-energy-saver) for details on how this feature works and how to configure templates. ::: :::info ### **Tip:** You can view incoming messages in the [Device Inspector](/docs/1nce-os/1nce-os-device-inspector) in the 1NCE OS portal. ::: If disabled, a plain-text message will be sent instead. ## ⚙️ Configuration options The following configuration options are available for customizing the CoAP client behavior: | Config Option | Description | Default | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `CONFIG_COAP_SAMPLE_SERVER_HOSTNAME` | CoAP server hostname | `coap.os.1nce.com` | | `CONFIG_COAP_SAMPLE_SERVER_PORT` | CoAP server port (5684 if DTLS enabled, otherwise 5683) | Auto | | `CONFIG_COAP_URI_QUERY` | URI query string used as topic parameter | `t=test` | | `CONFIG_COAP_SAMPLE_REQUEST_INTERVAL_SECONDS` | Interval between uplink messages (in seconds) | `60` | | `CONFIG_NCE_DEVICE_AUTHENTICATOR` | Enables device onboarding with 1NCE SDK | `y` | | `CONFIG_NCE_UPLINK_MAX_RETRIES` | Max retry attempts for uplink CoAP requests | `5` | | `CONFIG_NCE_DTLS_HANDSHAKE_TIMEOUT_SECONDS` | DTLS handshake timeout | `15` | | `CONFIG_NCE_MAX_DTLS_CONNECTION_ATTEMPTS` | Max DTLS failures before retrying onboarding | `3` | | `CONFIG_NCE_DTLS_SECURITY_TAG` | DTLS TAG used to store credentials on the modem | `1111` | | `CONFIG_NCE_ENABLE_DTLS` | Enables DTLS for secure CoAP communication. This is **automatically enabled** when both `ZEPHYR_NCE_SDK_MODULE` and `NCE_DEVICE_AUTHENTICATOR` are enabled. | `y` if `ZEPHYR_NCE_SDK_MODULE && NCE_DEVICE_AUTHENTICATOR`, else `n` | *** ### 🔋 Payload Configuration Depending on whether the Energy Saver feature is enabled: * If `CONFIG_NCE_ENERGY_SAVER` is **disabled**: | Config Option | Description | Default | | ---------------- | ----------------------------------- | ----------------------------------------- | | `CONFIG_PAYLOAD` | Message sent to 1NCE IoT Integrator | `{"text": "Hi, this is a test message!"}` | *** * If `CONFIG_NCE_ENERGY_SAVER` is **enabled**: | Config Option | Description | Default | | ------------------------------ | ----------------------------------------------- | ------- | | `CONFIG_NCE_PAYLOAD_DATA_SIZE` | Payload data size for the Energy Saver template | `10` | *** > ⚠️ **Note:** The default maximum length for `CONFIG_COAP_URI_QUERY` is **12 bytes**. > > To increase this limit, set: > > ```conf > CONFIG_COAP_EXTENDED_OPTIONS_LEN=y > CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE=`` > ``` ## 🧠 Device Controller The **Device Controller** allows your device to receive CoAP downlink messages using the 1NCE Management API. It supports sending downlink requests that your device can process in real-time. 📘 More info: [1NCE DevHub – Device Controller](/docs/1nce-os/1nce-os-device-controller) ### 🔁 Sending a Request Use the following `curl` command to send a CoAP request to your device: ``` curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices//actions/COAP' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "payload": "Data to send to the device", "payloadType": "STRING", "port": , "path": "/example?param1=query_example1", "requestType": "POST", "requestMode": "SEND_NOW" }' ``` Replace: * `` with your SIM’s ICCID * `` with your [OAuth token](/api/authorization/post-access-token-post/) *** #### 📩 Request Parameters | Parameter | Description | Example | | ------------- | --------------------------------------------- | ------------------------- | | `payload` | Data to send to the device | `"enable_sensor"` | | `payloadType` | Type of payload (`STRING`, `HEX`, etc.) | `"STRING"` | | `port` | Device port to receive the message | `3000` | | `path` | Request path and optional query | `"/example?param1=query"` | | `requestType` | CoAP method to use (`POST`, `GET`, etc.) | `"POST"` | | `requestMode` | Request mode (`SEND_NOW`, `SEND_WHEN_ACTIVE`) | `"SEND_NOW"` | ## 🔧 Zephyr Device Controller Configuration If `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` is enabled: | Config Option | Description | Default | | --------------------------------------- | --------------------------------------------------------------- | ------- | | `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` | Enables the device controller feature | `y` | | `CONFIG_NCE_RECV_PORT` | UDP port to listen for incoming CoAP messages | `3000` | | `CONFIG_NCE_RECEIVE_BUFFER_SIZE` | Buffer size for CoAP message handling | `1024` | | `CONFIG_NCE_DOWNLINK_MAX_RETRIES` | Max retry attempts for setting up downlink socket | `5` | | `CONFIG_NCE_COAP_MAX_URI_PATH_SEGMENTS` | Maximum number of URI path segments to support in CoAP requests | `5` | | `CONFIG_NCE_COAP_MAX_URI_QUERY_PARAMS` | Maximum number of query parameters allowed in CoAP requests | `5` | *** ## ⚠️ CoAP Limitations > CoAP messages — including **uplink and downlink** — are subject to strict option length limitations (especially for `URI-QUERY` and extended paths).\ > Make sure to increase buffer sizes if your topic or query strings exceed the default 12 bytes using: > > ```conf > CONFIG_COAP_EXTENDED_OPTIONS_LEN=y > CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE=`` > ``` ## 📤 Zephyr Output Example When the Zephyr application receives a CoAP message from the 1NCE API: ``` [00:00:02.275,817] [downlink_thread] NCE_COAP_DEMO: Downlink thread started... [00:00:02.276,336] [downlink_thread] NCE_COAP_DEMO: Listening on port: 3000 [00:00:07.847,869] [downlink_thread] NCE_COAP_DEMO: Received 72 bytes from server [00:00:07.847,930] [downlink_thread] NCE_COAP_DEMO: Received raw data: 48 02 1e 02 98 73 d5 1f d7 3a 5a 1c b7 65 78 61 |H....s.. .:Z..exa 6d 70 6c 65 10 3d 08 70 61 72 61 6d 31 3d 71 75 |mple.=.p aram1=qu 65 72 79 5f 65 78 61 6d 70 6c 65 31 ff 44 61 74 |ery_exam ple1.Dat 61 20 74 6f 20 73 65 6e 64 20 74 6f 20 74 68 65 |a to sen d to the 20 64 65 76 69 63 65 0a | device. [00:00:07.847,961] [downlink_thread] NCE_COAP_DEMO: CoAP Header: [00:00:07.847,991] [downlink_thread] NCE_COAP_DEMO: Version: 1 [00:00:07.848,022] [downlink_thread] NCE_COAP_DEMO: Type: CON [00:00:07.848,022] [downlink_thread] NCE_COAP_DEMO: CoAP Request Method: POST (0.02) [00:00:07.848,052] [downlink_thread] NCE_COAP_DEMO: Message ID: 7682 [00:00:07.848,052] [downlink_thread] NCE_COAP_DEMO: CoAP Options: [00:00:07.848,083] [downlink_thread] NCE_COAP_DEMO: Complete Path: [00:00:07.848,114] [downlink_thread] NCE_COAP_DEMO: /example [00:00:07.848,175] [downlink_thread] NCE_COAP_DEMO: CoAP Payload (binary): 44 61 74 61 20 74 6f 20 73 65 6e 64 20 74 6f 20 |Data to send to 74 68 65 20 64 65 76 69 63 65 0a |the devi ce. [00:00:07.848,236] [downlink_thread] NCE_COAP_DEMO: sent ack: 68 44 1e 02 98 73 d5 1f d7 3a 5a 1c |hD...s.. .:Z. [00:00:07.848,632] [downlink_thread] NCE_COAP_DEMO: CoAP ACK sent successfully ``` ## 📦 Ready-to-Flash Firmware for Thingy:91 We provide a **prebuilt HEX file** for Thingy:91 that you can flash directly to your device for quick testing.\ No build setup is required — just flash and go. 👉 **Download:** [Thingy:91 Prebuilt HEX](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/nce_coap_demo/thingy_binaries/zephyr.signed.hex) :::warning The firmware is configured with all LTE bands enabled, which may cause a delay of several minutes during the initial network connection while scanning for available bands. This is normal. ::: *** # 1NCE Zephyr blueprint - LwM2M Demo ## Overview The **1NCE LwM2M Demo** enables devices to communicate with 1NCE endpoints using the **LwM2M protocol** over CoAP, with optional DTLS for secure messaging. It supports control of LEDs, buzzers, sensors, and other objects via LwM2M standard object models. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – the device is currently connecting to the network * 🔵 **BLUE** – the device is currently bootstrapping * 🟢 **GREEN (10 seconds)** – the device is registered with 1NCE LwM2M server ### ✅ Supported Objects for LwM2M Actions 🔗 LwM2M actions can be tested using the [1NCE Action API](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/) or from the device controller tab in 1NCE OS UI. | Object | Path(s) | Description | Supported Boards | | ------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- | | Light Control | `/3311/0/5850` (1 Thingy:91 LED) `/3311/<0–3>/5850` (4 DK LEDS) | Boolean: LED on/off | All boards | | Light Color | `/3311/0/5706` | RGB LED color in HEX (e.g., `0xFF0000`) | Thingy:91 only | | Buzzer | `/3338/0/5850` | Boolean: Audible alert | Thingy:91 only | *** ## ⚙️ Configuration Options ### 🔐 Authentication & Server Setup | Config Option | Description | Default | | --------------------------------------------- | --------------------------------------------------------- | ------- | | `CONFIG_NCE_ICCID` | ICCID used as endpoint name and device identity | `""` | | `CONFIG_NCE_LWM2M_BOOTSTRAP_PSK` | Pre-shared key in HEX for bootstrap/auth | `""` | | `CONFIG_LWM2M_CLIENT_UTILS_SERVER` | LwM2M server URI (e.g., `coaps://lwm2m.os.1nce.com:5684`) | - | | `CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG` | Security tag for bootstrap server (credentials storage) | `1111` | | `CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG` | Security tag for main server (replaced after bootstrap) | `1112` | | `CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME` | Default LwM2M Server lifetime (in seconds) | `180` | 📌 The PSK (Pre-Shared Key) must match the credentials registered using the [1NCE PSK API](/api/1nce-os/create-pre-shared-device-key/) > ⚠️ The PSK **must be provided in HEX format**, not plain text. 💡 **Example:**\ If your desired PSK is the string `KeyPass123`, you must convert it to its hexadecimal representation. **Conversion:** * Input string: `KeyPass123` * HEX format: `4b657950617373313233` Use this HEX value (`4b657950617373313233`) when setting `CONFIG_NCE_LWM2M_BOOTSTRAP_PSK`. ✅ Tools for conversion: * Online: [RapidTables String to Hex](https://www.rapidtables.com/convert/number/ascii-to-hex.html) * Terminal (Linux/macOS): ```bash echo -n 'KeyPass123' | xxd -p ``` *** ## 🔓 Unsecured LwM2M (Testing Only) To run without DTLS (e.g., during integration testing): ```conf CONFIG_LWM2M_DTLS_SUPPORT=n CONFIG_LWM2M_CLIENT_UTILS_SERVER="coap://lwm2m.os.1nce.com:5683" ``` *** ## 🧩 Feature Modules ### Input Controls | Module | Description | Condition | | ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `CONFIG_APP_PUSH_BUTTON` | Enable push button support (Object 3347) | All boards: • Thingy:91 (1 button) • nRF9160 DK & nRF9151 DK (2 buttons) | | `CONFIG_APP_ONOFF_SWITCH` | Enable on/off switch input support (Object 3342) | DK boards only: • nRF9160 DK (2 switches) • nRF9151 DK (Buttons 3 and 4 are used as switches) | #### Main LwM2M Resources for Push Button and On/Off Switch Objects | Resource ID | Name | Type | Description | | ----------- | ------------------------ | ------- | -------------------------------------------------------- | | `5500` | Digital Input State | Boolean | `true` if pressed/on, `false` if released/off | | `5501` | Digital Input Counter | Integer | Number of times the button/switch has toggled | | `5518` | Timestamp of Last Change | Time | Time of the last change (press/release or on/off toggle) | 💡 **Note:** * Resource values can be monitored by sending an `observe-start` request to the relevant object (e.g., `/3347`) using 1NCE OS device controller. ### Output Controls | Module | Description | Condition | | -------------------------- | ------------------------------------ | -------------- | | `CONFIG_APP_LIGHT_CONTROL` | Enable LED output (Object 3311) | All boards | | `CONFIG_APP_BUZZER` | Enable buzzer output (Object 3338) | Thingy:91 only | *** ## 🧾 Device Identity Set device manufacturer and type: ```conf CONFIG_APP_MANUFACTURER="Nordic Semiconductor ASA" CONFIG_APP_DEVICE_TYPE="OMA-LWM2M Client" ``` 💡 **Notes:** * Those values are stored in the `/3/0/0` and `/3/0/17` resources of the device object. * The device object is not included in passive reporting, but it can be retrieved by sending a `Read` request to object `/3` using 1NCE OS device controller. *** ## 🔧 Logging Configure log levels for the application: ```conf CONFIG_APP_LOG_LEVEL_INF=y CONFIG_LOG=y ``` *** # 1NCE Zephyr blueprint - 1NCE FOTA Mender Demo ## Overview The **1NCE FOTA Mender Demo** enables firmware-over-the-air (FOTA) updates through [Mender.io](https://mender.io) using the 1NCE CoAP Proxy for secure and efficient communication. The device securely connects, authenticates, checks for firmware updates, downloads new versions, and updates itself. On the `Thingy:91`, the LED colors indicate the following statuses: * ⚪ **Flashing White** – Connecting to the network * 🟢 **Solid Green** – Firmware version 1 running * 🟡 **Flashing Green / Flashing Blue** – Firmware is being downloaded * 🔵 **Solid Blue** – Firmware version 2 running #### 📟 Development Kits (nRF9160DK / nRF9151DK) While the firmware is being downloaded, the DKs show a circular LED pattern across the four LEDs: * 🔄 LEDs 1 → 2 → 3 → 4 blink in sequence, repeating until the download is complete. *** ## Mender Integration This demo requires the [1NCE Mender Plugin](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/) to be installed and enabled. You can use prebuilt binaries and artifacts for quick testing. *** ## Running the demo ### 1️⃣ Build & Flash Flash the demo to the board using VS Code or nRF Connect for Desktop: * For **Thingy:91**, use [nRF Connect Programmer](https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop/Download). * For **nrf9151DK & nrf9160DK**, the firmware can be flashed directly from **VS Code**. > ⚠️ **Windows Path Length Warning** > > On **Windows**, long file paths may cause build errors during the demo compilation.\ > 👉 To avoid this issue, move the project folder to a shorter path such as: > > ```bash > C:\dev\fota_mender_demo > ``` ### 2️⃣ Accept the Device in Mender When starting the demo for the first time, the device will attempt to register with the Mender server. 🛡️ **Manual Approval Required:**\ You must manually **accept the device** in the [Mender Dashboard](https://hosted.mender.io/ui/) before it can receive any updates. #### 🔁 After acceptance: * The device will **periodically check** for firmware updates * Its **inventory** (such as IMEI, artifact name, and device type) will be updated in the Mender dashboard :::tip ### You can view this info under the **Devices** section after the device is authorized. :::
![Device listed in Mender dashboard after acceptance.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/501c9f2fff0543aa4368fc487586f78edcfbe90794f302c30aa1d93e7b3891f9-image.png)
### 3️⃣ Bump Version & Rebuild To simulate a firmware update: 1. Open your `prj.conf` file 2. Update the following configuration options to reflect the new version: ```conf CONFIG_APPLICATION_VERSION=2 CONFIG_ARTIFACT_NAME="release-v2" ``` 3. Rebuild the firmware using your preferred method (e.g., west build, VS Code) ### 4️⃣ Create & Upload Mender Artifact 📦 Firmware updates in Mender are distributed as **artifacts**. #### 🛠️ Create Artifact with `mender-artifact` 1. **Install** the [Mender Artifact Tool](https://docs.mender.io/downloads#mender-artifact) 2. **Run** the following command to generate a new artifact: :::note ### Replace the placeholders with your actual values. ::: ```bash mender-artifact write module-image \ -t thingy \ -o release-v2.mender \ -T release-v2 \ -n release-v2 \ -f build/nce_fota_mender_demo/zephyr/zephyr.signed.bin \ --compression none ``` 📌 Replace values as needed for your device: * `-t`: Device type (`CONFIG_MENDER_DEVICE_TYPE`) * `-n`: Artifact name (`CONFIG_ARTIFACT_NAME`) * `-T`: Payload type (e.g. release-v2) * `-f`: Firmware binary file path (usually `build/nce_fota_mender_demo/zephyr/zephyr.signed.bin`) 3. **Upload** the generated `.mender` file to the **Releases** section in the Mender dashboard.
![Upload the new artifact to the Releases section.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/d32e239300d120c8217e3fb36ecb5f3d98e8d0f99d8ccfdf11e1c6463913f301-image.png)
## 5️⃣ Deployment Creation Once your artifact is uploaded to the Mender **Releases** section, you're ready to deploy it to your device(s). 1. Navigate to the **Deployments** tab in the Mender dashboard. 2. Click **Create Deployment** and follow the wizard: * Select the **target device** or **device group**. * Choose the **artifact** you previously uploaded.
![Create a deployment in the Mender dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/fe24d9c5ab727993dd50a9f2a72ccf905ad8674e7f340f9d5dee4227501c5017-image.png)
*** #### 🚦 Deployment Status Flow After creation, the deployment will appear in the list with an initial status of `pending`.\ As your device contacts the Mender server, the status will progress automatically: ``` pending → downloading → rebooting → installing → success ✅ / failure ❌ ```
![Deployment status flow in Mender dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/d18c6b7558331c4e3116d3c41c543e88a80a1a055cb230a20473547cf39673c8-image.png)
*** ## ⚙️ Configuration Options The following configuration options are available for customizing the Mender FOTA demo: ### 🧩 General Options | Config Option | Description | Default | | ------------------------------------------------- | ------------------------------------------------ | -------------- | | `CONFIG_APPLICATION_VERSION` | Application version reported to Mender | `1` | | `CONFIG_ARTIFACT_NAME` | Mender artifact name (used in artifact creation) | `"release-v1"` | | `CONFIG_MENDER_DEVICE_TYPE` | Device type used for update compatibility | `"thingy"` | | `CONFIG_MENDER_FW_UPDATE_CHECK_FREQUENCY_SECONDS` | Firmware update check interval (in seconds) | `30` | | `CONFIG_MENDER_AUTH_CHECK_FREQUENCY_SECONDS` | Auth check interval (when unauthorized) | `30` | *** ### 🔐 Secure Communication | Config Option | Description | Default | | ----------------------------------- | ----------------------------------------------------- | -------------------------- | | `CONFIG_MENDER_URL` | Mender backend URL | `"eu.hosted.mender.io"` | | `CONFIG_NCE_MENDER_COAP_PROXY_HOST` | CoAP proxy hostname provided by 1NCE | `"coap.proxy.os.1nce.com"` | | `CONFIG_COAP_SERVER_PORT` | CoAP server port (5684 if DTLS is enabled, else 5683) | `Auto` | | `CONFIG_NCE_MENDER_COAP_URI_PATH` | URI path for proxying CoAP requests to Mender | `"mender"` | *** ### Unsecure CoAP Communication By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. To test unsecure communication (plain CoAP), disable the device authenticator by adding the following flag to `prj.conf` ``` CONFIG_NCE_DEVICE_AUTHENTICATOR=n ``` *** ## 📦 Ready-to-Flash Firmware for Thingy:91 For quick testing, we provide **prebuilt firmware binaries** that can be flashed directly to your Thingy:91 device — no build setup required. Available prebuilt files: | Version | Binary (.bin) | HEX (.hex) | Mender Artifact (.mender) | | ------------ | ---------------- | ---------------- | ------------------------- | | `release-v1` | `release-v1.bin` | `release-v1.hex` | `release-v1.mender` | | `release-v2` | `release-v2.bin` | `release-v2.hex` | `release-v2.mender` | 👉 **Flash directly using:** [`release-v1.hex`](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_fota_mender_demo/thingy_binaries/release-v1.hex) or [`release-v2.hex`](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_fota_mender_demo/thingy_binaries/release-v2.hex) :::warning These builds enable all LTE bands, so the initial network registration may take several minutes while scanning. ::: *** # 1NCE Zephyr blueprint - 1NCE Memfault Demo ## Overview The **1NCE Memfault Demo** enables Zephyr-based devices to send diagnostics and fault data via **CoAP** using the **1NCE CoAP Proxy**. This is useful for tracking faults, crashes, and network issues in IoT devices. Communication can optionally be secured using **DTLS**. On the `Thingy:91` device, LED indicators show the following statuses: * 🔵 **BLUE** – Network connected * 🟢 **GREEN** – Memfault data sent successfully * 🔴 **RED** – Failed to send Memfault data *** ## 🔌 Memfault Integration To use this demo, install and enable the [Memfault Plugin](/docs/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/) for 1NCE OS. 📦 SDK Requirement: [nRF Connect SDK v2.8.0](https://docs.nordicsemi.com/bundle/ncs-2.8.0/page/nrf/gsg_guides.html) *** ## ▶️ Running the Demo ### 1️⃣ Build & Flash **Build** the project for either `thingy91/nrf9160/ns` or `nrf9160dk/nrf9160/ns` or `nrf9151dk/nrf9151/ns`. * Flash using **VS Code** for DKs or **nRF Connect Programmer** for Thingy:91. * Firmware path (Thingy:91):\ `build/nce_debug_memfault_demo/zephyr/zephyr.signed.hex` > ⚠️ On Windows, avoid long folder paths to prevent build errors. > > Use something like `C:\dev\memfault_demo` *** ### 2️⃣ Upload Symbol File to Memfault To enable metric processing: * Go to **Memfault Dashboard > Symbol Files** * Upload:\ `build/nce_debug_memfault_demo/zephyr/zephyr.elf` 📘 [Symbol File Guide](https://docs.memfault.com/docs/mcu/symbol-file-build-ids)
![Upload the ELF symbol file to Memfault.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/81f6622dca350284f5af6fb7f4e8b3571f336887884009a12741c0475a49726c-image.png)
![Memfault symbol file upload confirmation.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/41038e9dee3d836b4d387b0e3d9f3e2633c28dfc21e1f3446f4ae021ce91a307-image.png)
*** ### 3️⃣ Authorize the Device The device will register itself using the SIM’s **ICCID** as its serial number.\ You’ll see it appear in the **Devices** view of Memfault.
![Device listed in Memfault dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/2e67755f68f053bc70ee280135d0e4dd3ab774d3d6df18acb63fba7ebb7ebb8e-image.png)
*** ### 4️⃣ Generate Events On boot, two events are sent automatically: * `heartbeat`: Contains standard metrics * `reboot`: Reports cause of last reboot Use the CLI to trigger more: ```bash nce post_chunks # Push buffered data now nce divby0 # Trigger division-by-zero crash nce sw1 # Increment switch_1_toggle_count nce sw2 # Log switch_2_toggled event nce disconnect # Simulate disconnection and reconnection ``` The overview dashboard shows a summary of recent device issues:
![Memfault dashboard overview of device issues.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/e4ed2f35b3f1d77a6ad907eceebf6906d8335afc55df7d7103e777a0e6e13326-image.png)
*** ## 🔘 Fault Injection via Buttons | Button / Switch | Description | | --------------- | --------------------------- | | Button 1 | Stack overflow | | Button 2 | Division by zero | | Switch 1 | Custom metric: toggle count | | Switch 2 | Event trace: switch toggled | 💡 On Thingy:91, use `nce` CLI instead (only Button 1 available) *** ## 📶 Connectivity Metrics Enabled by default with: ```conf CONFIG_MEMFAULT_NCS_LTE_METRICS=y CONFIG_NCE_MEMFAULT_DEMO_COAP_SYNC_METRICS=y CONFIG_NCE_MEMFAULT_DEMO_CONNECTIVITY_METRICS=y ``` ### Standard LTE Metrics * `ncs_lte_time_to_connect_ms` * `ncs_lte_connection_loss_count` * `ncs_lte_tx_kilobytes` * `ncs_lte_rx_kilobytes` ### Additional Metrics * `ncs_lte_nce_operator` * `ncs_lte_nce_bands` * `ncs_lte_nce_current_band` * `ncs_lte_nce_apn` * `ncs_lte_nce_rsrp_dbm` ### Sample Connectivity dashboard configuration:
![Sample Connectivity dashboard configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/c5697d3f72aa6ee62fbbb1dc5a82f47da0e8d8b31e628a876f9a77cc4a064925-image.png)
#### Sync Succes chart configuration:
![Sync Success chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/20e40244b6384072f88c01471319569f452abc53b64a33a32aceb4f46879fe66-image.png)
#### To create a new metrics chart:
![Create a new metrics chart](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/b7aa40b5bc2624449230752ad9d5cb07b0473d557bb0ffebc186d3ad7566619e-image.png)
#### Signal quality chart configuration:
![Signal quality chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/dcf3ed5f1393f075b296a1372bb678653afe47971dfd6e8bd7ccbc6d32c694ed-image.png)
#### Sent KB chart configuration:
![Sent KB chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/2f7342db1ee3c9efc9fbdcddec5046201e55e133be5929c2891efa01ab160159-image.png)
*** ## 🔐 DTLS Configuration To enable secure communication: ```conf CONFIG_NCE_MEMFAULT_DEMO_ENABLE_DTLS=y CONFIG_NCE_SDK_ENABLE_DTLS=y CONFIG_NCE_DEVICE_AUTHENTICATOR=y CONFIG_NCE_SDK_DTLS_SECURITY_TAG= ``` * If onboarding is required, set `` to an empty tag and the demo will authenticate via 1NCE automatically. * On failure (3x), re-onboarding is triggered automatically. *** ## ⚙️ Configuration Options ### General Options | Config Option | Description | Default | | ------------------------------------------------------------ | --------------------------------------------------------------------------- | ------- | | `CONFIG_NCE_MEMFAULT_DEMO_PERIODIC_UPDATE` | Enable periodic Memfault updates | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_PERIODIC_UPDATE_FREQUENCY_SECONDS` | Interval between updates (seconds) | `30` | | `MEMFAULT_METRICS_HEARTBEAT_INTERVAL_SECS` | Heartbeat interval (in header file) in `config/memfault_platform_config.h` | `30` | | `CONFIG_NCE_MEMFAULT_DEMO_CONNECTIVITY_METRICS` | Collect Additional connectivity metrics | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_COAP_SYNC_METRICS` | Tracks successful/failed syncs | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_PRINT_HEARTBEAT_METRICS` | Print heartbeat metrics to serial log | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_DISCONNECT_DURATION_SECONDS` | Simulated disconnect duration | `20` | | `CONFIG_NCE_MEMFAULT_DEMO_ENABLE_DTLS` | Enable secure CoAP over DTLS | `n` | *** ## 🆘 Need Help? Open an issue on GitHub for: * ❗ Bug reports * 🚀 Feature requests * 📝 Documentation issues * ❓ General questions 👉 [Create a new issue](https://github.com/1NCE-GmbH/blueprint-zephyr/issues/new/choose) *** Made with 💙 by the 1NCE Team. --- # Services Overview Source: https://help.1nce.com/docs/1nce-os/1nce-os-services-overview/
![](/img/1nce-os/1nce-os-services-overview/1nce-os-architecture.png)
# 1NCE OS Overview 1NCE OS offers different services to support connecting IoT-Devices within our network. The new service is offered on both sides, integration of devices and integration of cloud services or custom webhooks. ## Device Authenticator Authenticate IoT devices against external cloud systems based on the identity of the used IoT SIM. An IoT SIM in any form factor is placed into the IoT device and acts as authenticating element by relying on the same network authentication mechanisms as 1NCE Connect. It replaces provisioning processes which include secret flashing during manufacturing and creation of secure device twins in external cloud services. [Device Authenticator](/docs/1nce-os/1nce-os-device-authenticator/) ## IoT Integrator The IoT Integrator includes the Device Integrator and the Cloud Integrator. ### Device Integrator The device integrator supports to connect devices to 1NCE managed services. For that three different protocols, UDP, CoAP and LwM2M are offered. [Device Integrator](/docs/1nce-os/1nce-os-device-integrator/) ### Cloud Integrator The Cloud Integrator allows to create, manage and use 1NCE webhooks and direct AWS Integrations. This provides the possibility for a customer to forward data from their devices to customer-defined HTTPS endpoints or an AWS Account with real-time information. [Cloud Integrator](/docs/1nce-os/1nce-os-cloud-integrator/) ### Device Controller The Device Controller supports sending messages to the device via the 1NCE OS managed services. For that we offer three protocols in Device Integrator. [Device Controller](/docs/1nce-os/1nce-os-device-controller/) ## Device Inspector The Device Inspector combines an interface for analytic, monitoring and controlling tasks for IoT devices. [Device Inspector](/docs/1nce-os/1nce-os-device-inspector/) ## Device Locator With this service, the location tracking of devices and the possibility of defining geofences for devices can be controlled. [Device Locator](/docs/1nce-os/1nce-os-device-locator/) ## Plugin System Plugins extend the capabilities of the 1NCE platform with services provided by 3rd party vendors. You can enable additional functionality by installing a plugin. ## Energy Saver 1NCE offers the energy saver to translate messages coming from IoT devices. Using this feature, the messages send from the devices can be shortened, which in the end is saving energy. In the frontend, an overview on how much energy is saved is provided. [Energy Saver](/docs/1nce-os/1nce-os-energy-saver/) ## Admin Logs The 1NCE Admin Logs provides an intermediate storage of messages from devices. From the Admin Logs, the messages can be viewed via the Web Interface or queried using the Management API for further processing. [Admin Logs](/docs/1nce-os/1nce-os-admin-logs/) --- # Data Processing Agreement Source: https://help.1nce.com/docs/1nce-os/1nce-os-services-overview/1nce-os-data-processing-agreement/ ## Data Processing Agreement The Data Processing Agreement PDF can be found here: [https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf](https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf) --- # Terms of Use Source: https://help.1nce.com/docs/1nce-os/1nce-os-services-overview/1nce-os-terms-of-use/ ## Terms of Use The Terms of Use PDF can be found here: [https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf](https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf) --- # Account & Orders Source: https://help.1nce.com/docs/1nce-portal/portal-accounts-orders/ # Account The "Account" tab allows the customer to view and edit their personal/company data, billing and shipping addresses as well as to manage the Auto-Top-Up payment. > ❗️ Non-Changeable Data Fields > > Due to legal reasons we cannot allow to change the company name or billing country of the billing address. For assistance please contact our support. In the Customer and User Data dropdown, the contact information and account details for the root organization and for the logged-in user can be viewed and changed. Note that the e-mail address shown in the Customer Data column is the main contact where all invoices are being sent to digitally. An additional e-mail address can be stored which receives the invoices in copy, for example the accounting department. Please select the category "Invoice" for that.\ Furthermore the category "Volume Notifications" can be selected. This includes all e-mails on volume notifications for data/SMS as well as reaching the monthly set volume limit.\ The language selection defines the contact language meaning e-mails, invoices and service notifications. In the User Data column information regarding the currently logged-in user data can be viewed and changed. The logged-in user (no matter which role) can change their personal details like name and e-mail address as well as password. These details can also be changed by an Admin or Owner via the "Users" tab except the password for the roles Owner, Admin and User. The Billing and Shipping Addresses dropdown shows all saved billing and shipping addresses. Existing entries can be changed and new addresses can be added by the customer for future orders. The addresses are stored and will appear each time the user orders additional SIM cards or Top-Ups. The Payment Details Auto-Top-Up dropdown allows to save/delete credit card details if the customer wishes to activate Auto-Top-Up for single or all SIMs. The Auto-Top-Up feature can be enabled for particular SIMs in the "My SIMs" tab or for all SIMs in the "Configuration" tab. An API call is also available.
![220422_Account_tab.PNG](/img/1nce-portal/portal-accounts-orders/c341635-220422_Account_tab.PNG)
*** # Orders In the "Orders" tab, all orders from the organization's 1NCE account are listed. The table provides an overview of the important order parameters as well as the current status of an order. The status indicator (completed, in preparation or cancelled) can be used to monitor pending orders.\ On this page, previous invoices of specific orders can be downloaded. Additionally, a CSV list of all SIMs of a particular order can be downloaded using the link in the "Affected SIMs" column. This list for a dedicated order consists of ICCID, label, IMSI and MSISDN of the SIMs. In case there has been any correction to the order, the corrected or updated invoices can be downloaded in the column "Additional Documents".
![20220218_Orders.PNG](/img/1nce-portal/portal-accounts-orders/9242b3a-20220218_Orders.PNG)
--- # Configuration Source: https://help.1nce.com/docs/1nce-portal/portal-configuration/ ## Network Settings The network settings contain the basic information to get the SIM Cards connected to the 1NCE network. | Parameter | | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1NCE APN` | Needs to be set in the very first step to set up a connection to the network. | | `SMSC Number` | Is generally needed to aim all Mobile Originated SMS in the network, although this setting is rarely needed for manual configuration. | | `Internet Breakout` | Shows the IP addresses used for all 1NCE SIMs to access the public internet through a NAT. Get all available [Internet Breakout IPs](/docs/network-services/network-services-internet-breakout) | | `IP Address Space` | Shows the IP spaces assigned to SIMs in the given organization. Each SIM has a static IP address which can to be used for direct access via the VPN Service. Additional IP spaces will be assigned for new SIM orders if the remaining IP space is not large enough. | | `IP Addresses` | Shows the availability of the IP address spaces assigned to the organization. |
![Network Settings in the Configuration tab.](/img/1nce-portal/portal-configuration/5f971fc-network-settings.jpg)

Network Settings in the Configuration tab.

*** ## Breakout Settings The Internet Breakout setting in the configuration tab allows you to configure the ideal network flow for your SIMs cards for public-facing internet access and private connectivity through VPN. The 1NCE Internet Breakout can be configured in two different variances, which offer different functionality. - Automatic Mode - Manual Mode The breakout setting allows you to select the nearest local Internet Breakout to minimize latency in data transfer. Your SIM card can either **Automatically **select the geographically nearest breakout, or you can **Manually **set the location of the breakout. For more information on the 1NCE Internet Breakout Service, please visit the [Internet Breakout](/docs/network-services/network-services-internet-breakout) documentation page. > 📘 Default Setting > > With the release (20.09.2022) of the configurable Internet Breakout setting, existing customers' breakout will remain in Europe (Frankfurt) as before the feature introduction in September 2022. > > New Organizations and newly created sub-organizations will use Automatic Mode by default. This setting can be changed in the 1NCE Portal configuration tab.
![Configuration of Breakout settings for Automatic or Manual mode.](/img/1nce-portal/portal-configuration/1cca9e3-220920_Breakout_Settings.PNG)

Configuration of Breakout settings for Automatic or Manual mode.

*** ## Monthly Limits By using "Monthly Limits" a customer can set an individual monthly data and SMS limit. The SMS limit can be configured separately for Mobile Originated (MO) and Mobile Terminated (MT) SMS. These limits will be applied to all of the customer's SIMs. By checking or unchecking the boxes these options can be set or cancelled easily at any time. The limits apply to the period of the calendar month. Putting another limit in the same month will not reset the previously consumed quota. Example: The first limit is 100 MB. After reaching it you put in 200 MB as a new limit. Now only 100 additional MB can be consumed because the previously consumed 100 MB are considered. ### Exceeding the Limits When the self-set limits are exceeded, error or warning messages are triggered based on the type of limit. #### Data Session When the limit is reached, new PDP data sessions will be rejected: **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** However, some devices might retry indefinitely to reconnect in such a case. 1NCE strongly advices to use a back-off approach in this rejection case to not flood the network with PDP session requests. #### MT-SMS Using the 1NCE API, if the self-set limit for MT-SMS is reached, **Traffic limit of X SMS per month exceeded** is returned as error. In the 1NCE Portal **Set monthly limit of SMS exceeded** is shown, when the MT-SMS limit was reached and a new SMS is issued. #### MO-SMS For **MO-SMS** no notification will be shown in the 1NCE Portal or Data Stream. The SMS will be rejected by the network resulting in an error return code from the device modem.
![Monthly Limits configuration for Data and MO-/MT-SMS.](/img/1nce-portal/portal-configuration/8ee837c-1NCE_Limits.png)

Monthly Limits configuration for Data and MO-/MT-SMS.

*** ## Global IMEI Lock A global IMEI Lock can be set for all SIM Cards of the organization. The IMEI lock works by saving the IMEI of the device the SIM is installed in. With the feature enabled, the 1NCE network will only accept the saved device IMEI - SIM card combination to access the network resource. Any other IMEI - SIM combination will be refused. If this feature is activated, the IMEI lock will be set during the next network attach. Consequently the SIM card can only be used with the current device. For new SIM Card orders a checkbox can be selected to enable the IMEI lock by default. This way newly ordered SIMs will have the IMEI Lock set automatically. A separate IMEI lock for individual cards of the organization can be set either via the 1NCE API or in the "My SIMs" tab.
![Global IMEI SIM lock settings.](/img/1nce-portal/portal-configuration/426b669-1NCE_IMEI_Lock.png)

Global IMEI SIM lock settings.

*** ## Auto Top-Up Automatic Top-Ups can be configured globally for all SIMs of an organization. The top-up will be automatically booked once a SIM card has \<20 % data and/or SMS volume. The check for low volume and potential Top-Up process if the SIM volume is less than 20%, are performed every four hours at 0:00, 4:00, 8:00, 12:00, 16:00, and 20:00 CET. To use this feature customers have to add their credit card details in the "Account" tab. By ticking the check-box it is possible to activate the auto-top-up for all future SIM orders by default. This feature can also be individually (de-)activated for a single SIM card via the Management API or the tab "My SIMs" and then the SIM-Detail page.
![Auto Top-Up configuration for enabling global SIM top up.](/img/1nce-portal/portal-configuration/4bcd521-1NCE_Auto_Top-Up.PNG)

Auto Top-Up configuration for enabling global SIM top up.

*** ## Data Streams The 1NCE Data Streaming Service allows customers to subscribe to real-time events and usage data for all SIM Cards by pushing data directly to the customer's server or an already integrated cloud service such as AWS Kinesis, S3, DataDog or Keen.io. The Data Streams configuration shows a list of all currently configured streams including the name, API type, stream type, URL, status indicator and controls for each stream. Each stream can be controlled individually. Besides basic stop, start and delete, a stream integration can be restarted. A restart needs to be performed if the stream enters a error state and needs to be recovered. To create a new data stream integration click on the New Data Stream button. Further details on how to setup a stream integration can be found in the [Data Streamer Setup Guides](/docs/platform-services/platform-services-data-streamer/data-streamer-setup-guides/) section of the Developer Hub.
![Overview of the current Data Streamer integrations.](/img/1nce-portal/portal-configuration/dc28289-1NCE_Data_Streamer.PNG)

Overview of the current Data Streamer integrations.

*** ## SMS Forwarding Configuration The SMS Forwarding configuration allows for receiving Mobile Originated (MO) SMS with a custom HTTP endpoint integration. For the configuration, the customer needs to insert the URL of the server, which shall receive the SMS. Further necessary details on configuration of SMS forwarding can be found in the [SMS Forwarding Service](/docs/platform-services/platform-services-sms-forwarder/) section of the Developer Hub.
![Configuration of the SMS Forwarding Service.](/img/1nce-portal/portal-configuration/3c9f0a2-1NCE_SMS_Forwarder.PNG)

Configuration of the SMS Forwarding Service.

*** ## OpenVPN Configuration OpenVPN is the recommended application setup by 1NCE to establish a secure, bidirectional data connection between the 1NCE network and the customer server. Dependent on the selected Internet Breakout option, OpenVPN might not be available (Automatic Mode) or needs a region specific configuration (Manual Mode). ### Automatic Mode
![VPN not available in Automatic Mode, the Breakout Setting needs to be changed to a manual region.](/img/1nce-portal/portal-configuration/c117bf2-vpn-auto.jpg)

VPN not available in Automatic Mode, the Breakout Setting needs to be changed to a manual region.

### Manual Mode (Europe) When the Manual Mode is selected the VPN configuration shown is dependent on the selected region. When changing the breakout region, note that the VPN configuration needs to be manually adapted as well. In such a case please download the new, region-specific configuration and setup a new VPN client.
![Specific configuration for Manual Mode (Europe) breakout.](/img/1nce-portal/portal-configuration/f7e1dbe-vpn-eu.jpg)

Specific configuration for Manual Mode (Europe) breakout.

The OpenVPN client needs to be installed on the customer server to which the SIMs should access via the VPN client IP. For the OpenVPN connection to the 1NCE network a configuration file and credentials file is needed. These files can be downloaded in this section of the 1NCE Customer Portal. There are two different versions for Windows and for Linux/MacOS available. For more details about the VPN Service, its setup and operation users can proceed to the [VPN Service](/docs/network-services/network-services-vpn-service/) section of the Developer Hub. --- # Dashboard Source: https://help.1nce.com/docs/1nce-portal/portal-dashboard/ After logging into to the 1NCE Customer Portal, an overview Dashboard is presented. The page shows the current SIM status, volume usage and a current order overview from the organization. ![1NCE_Portal_Dashboard.png](/img/1nce-portal/portal-dashboard/38ec2f5-1NCE_Portal_Dashboard.png) *** # SIM Status The "SIM Status" tile shows the current percentage of 1NCE SIMs that are activated and deactivated. SIMs can be (de-)activated by the customer to disable/enable the SIM specific connectivity. This process can be done via the 1NCE Portal or the 1NCE API. *** # Data Volume & Usage Regarding the data volume and usage, two tiles are presented in the dashboard. Details about the SIM specific quota and usage can be viewed in the "My SIMs" tab. The "Data Volume" tile shows the amount of SIMs with sufficient volume (greater 20%), low volume (less than 20%), and no volume. SIM Cards with sufficient or low volume still operate as expected, but an eye should be kept on SIMs with low volume. SIMs with the status "No Volume" have exceeded the purchased volume and have been blocked from accessing the data connection. These SIMs need to be topped up to receive new data volume credits. They can still connect to the network and send/receive SMS if sufficient SMS volume is present. The overall data usage of the organization is shown in the "Data Usage" plot. This plot shows the accumulated weekly volume in megabytes used over the last eight weeks. For more detailed usage records, the 1NCE API or 1NCE Data Streamer integration can be used. *** # SMS Volume & Usage Similar to the data volume and usage, two tiles for the SMS volume and usage are presented in the dashboard. Details for specific SIMs can be accessed via the "My SIMs" page. The SMS volume tile shows the amount of SIMs with sufficient volume (more than 20%), low volume (less than 20%), and no volume. Once a SIM has no SMS volume left, the data services can still be used but no further SMS can be sent or received. The SIM needs to be topped up to receive new SMS credits. The SMS usage is shown in a plot accumulated weekly for the last eight weeks. For more detailed usage records, the 1NCE API or 1NCE Data Streamer integration can be used. *** # Latest Orders In the "Latest Orders" tile, the past five orders with date and order ID references are shown in a quick access table. More information about the last orders can be accessed via the "Details" button. A new order can be directly triggered with the "Reorder" button. --- # Performance & Support Source: https://help.1nce.com/docs/1nce-portal/portal-performance-support/ # Performance The performance dashboard provides an insight into the key components and their current status of the 1NCE Services. In case of any incident, the status of the particular service will change accordingly. Customers can use this page to get a better understanding of a current incident and receive updates. Below the overview, a list of recent incidents in the network with a detailed description is listed.
![The 1NCE Performance dashboard, showing the current status of all 1NCE Services.](/img/1nce-portal/portal-performance-support/9789412-performance-page.jpg)
*** # Support Through the "Support" tab, 1NCE customers can quickly access documentation resources as well as technical support and customer service. On the page, links to the 1NCE Developer Hub, API Reference and a search integration for the documentation is given.
![Support DevHub.PNG](/img/1nce-portal/portal-performance-support/ef6274e-Support_DevHub.PNG)
Technical support and customer service is provided either directly via phone or by placing a new service request ticket. The access to technical support is only available for existing customers. Customer service is provided either in German or English language. Telephone support is available from Monday to Friday from 9 a.m. to 6 p.m. (CET/CEST) (except for national public holidays). Tickets are mainly processed within the service hours. --- # My SIMs & SMS Console Source: https://help.1nce.com/docs/1nce-portal/portal-sims-sms/ The "My SIMs" tab provides an overview of all SIMs currently attached to the specific organization. This page is used as an overview and to configure all SIM functionalities from the 1NCE Portal.
![20220214_SIM List.PNG](/img/1nce-portal/portal-sims-sms/73e4c9a-20220214_SIM_List.PNG)
*Overview of the My SIMs page, showing all SIMs of the organization.* *** # SIM Overview The view of all SIMs can be customized by altering the filter options or by using the search function to filter for specific parameters. The search option allows the user to search for a certain SIM by IMSI, Label, ICCID or MSISDN. The search supports a partial search as well. Basic global filtering for data and SMS volume and SIM card status can be applied. The values in the columns can be sorted in an ascending or descending order. By default the table is sorted by ICCID. The table can be sorted and filtered via the column titles. When a column is sorted or filtered an icon becomes visible. Further, the shown columns can be (de-)activated to select only the ones of interest using the "Adjust Columns" feature. Note, that for large number of SIM Cards there can be multiple pages of the list view. The number of SIMs per page can be set manually and has a maximum number of 500. Below, an explanation of all available columns to select from: ## Status | Parameter | Description | | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Activated` | Green checkmark, indicating that full SIM functionality is activated and the SIM can connect to the 1NCE services. | | `Deactivated` | Black cross, indicating that the SIM is deactivated. The SIM cannot connect to the 1NCE network. | | `Expired` | The `Expired` status indicates that the SIM card has reached the end of its lifetime and is no longer active. This means the SIM is fully suspended in the network and cannot connect anymore. Using a Lifetime Extension can reactivate the SIM. | ## Session | Parameter | Description | | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Online` | Green Light: The SIM has established a data session. When a SIM device does not properly close the PDP data session, this status will remain until the device is flushed from the network. | | `Offline` | Red Light: The SIM device is not connected to the 1NCE network. | | `Attached` | Amber Light: The SIM is attached to a mobile network, but has no active data session. When a SIM is not properly detached from a network, this status will remain until the device is flushed from the network. | ## SIM Details | Parameter | Description | | --- | --- | | `ICCID` | Unique serial of the SIM card. | | `MSISDN` | Phone number of the SIM card. The SIM can not be used for voice services or to receive/send SMS to external parties. The chapters [SMS Services](/docs/connectivity-services/connectivity-services-sms-services) and [SMS Forwarding Service](/docs/platform-services/platform-services-sms-forwarder) provide more information. | | `IMEI(SV)` | Identifier of the device the SIM is inserted into. The IMEI displayed in the 1NCE Portal is retrieved from the network during PDP context activation, the format is as follows: IMEI + SV (software version), based on the standard specification 3GPP TS23.003. See the IMEI Reference for more information. | | `IMEI Lock` | Status of the IMEI lock for this specific SIM. If enabled the SIM is bound to the current device. See the IMEI Lock Reference for more information. | | `IP Address` | Static IP address of the specific SIM. Used for accessing the SIM via 1NCE VPN Services. | | `SIM Type` | Specific type of SIM card, FlexSIM or eSIM. | | `Tariff` | Details about the tariff of the specific SIM showing the data and SMS volume. | | `Label` | Self-set label text for the specific SIM card. | | `Auto-Top-Up` | Indicator if Auto-Top-Up is enabled for this SIM. | | `Data Usage` | Colored indicator of the remaining data quota. Green > 20% remaining, Yellow \< 20% available, Red = 0 % remaining. | | `SMS Usage` | Colored indicator of the remaining SMS quota. Green > 20% remaining, Yellow \< 20% available, Red = 0 % remaining. | ## SIM Export The complete and customized SIM Card table can be exported as a CSV-file if needed by using the "Export SIMs" button. As it might take some time to export a larger list of SIMs, the user gets an e-mail notification as soon as the export is completed and can be downloaded from the SIM Export section underneath the SIM card table. This export also includes the PIN and PUK of each SIM which might be needed for certain devices.
![20220214_Downloads.PNG](/img/1nce-portal/portal-sims-sms/4137a69-20220214_Downloads.PNG)
*SIM Export section below the SIM table* *** # SIM Management Each SIM card in the list view can be selected using the checkbox on the left side of each list entry. By selecting one or several SIMs the user can perform different actions like (de-)activating SIMs, setting the IMEI lock, configuring Auto-Top-Ups or manually recharging the SIM data and SMS volume. These actions can be triggered for the selected SIMs using the buttons in the action bar appearing once SIMs are selected. Additional SIMs can be ordered from here as well with the "Reorder" button on the top right of the table.
![20220214_Action bar.PNG](/img/1nce-portal/portal-sims-sms/cb80c15-20220214_Action_bar.PNG)
*Selected SIMs with open action bar* ## SIM Top-Up It is possible to manually book additional data and SMS volume for one or more selected SIM cards. With every Top-Up 500 MB and 250 SMS are added to the remaining volume. Top-Ups for single SIM cards can be booked in the detailed view of a card. More volume can be added by ordering multiple Top-Ups in a row. The booked volume is available as soon as the payment is received: | Payment method | Duration | | :------------- | :---------------- | | Bank transfer | Two to three days | | Credit card | Immediately | For automatically booked volume, please refer to our [Auto-Top-Up-feature](/docs/1nce-portal/portal-configuration#auto-top-up). ## SIM Deactivation The selected SIM can be deactivated to prevent an attachment to the 1NCE network. This feature is useful for disabling SIMs during shipping of devices or to force a reset of the connection. This function can also be used through the 1NCE API. Active attachments of SIMs will be purged and devices immediately disconnected. Subsequent attempts of the device to re-register will be refused by the network until the SIM is re-activated. Depended on the device logic this blocking might force some devices to get into an error state and prevent them from reconnecting to any network even if the SIM has been re-activated again. Implementing a soft- or hard-restart with an **exponential back-off** timer as part of the connectivity procedure of the device firmware is advised. This procedure should circumvent the potential delay in attaching after a SIM reactivation where the device was stuck in an error state. Please implement a back-off algorithm with at least 5-20 minutes between reattempts to not overload the network with undesired attach requests during SIM deactivations. After reactivating the SIMs, the network will once again allow the SIM to attach to the 1NCE network and use all services as usual. ## IMEI Lock The IMEI lock will only be set for the selected SIMs. It works by saving the IMEI of the device the SIM is installed in. With the feature enabled, the 1NCE network will only accept the saved device IMEI - SIM card combination to access the network resource. Any other IMEI - SIM combination will be refused. If this feature is activated, the IMEI lock will be set during the next network attach. As a consequence, the SIM card can only be used with the current device. To change the setting for all (future purchased) SIM cards please navigate to the tab [Configuration](/docs/1nce-portal/portal-configuration#global-imei-lock). ## Auto-Top-Up Automatic Top-Ups can be configured for all selected SIMs. The Top-Up will be automatically booked once a SIM card has \<20 % data and/or SMS volume. The check for low volume and potential Top-Up process if the SIM volume is less than 20%, are performed every four hours at 0:00, 4:00, 8:00, 12:00, 16:00, and 20:00 CET. To use this feature the customer has to add their credit card details to the account via the "Account" tab. To activate this for all (future) SIM cards please navigate to the tab [Configuration](/docs/1nce-portal/portal-configuration#auto-top-up). By ticking the check-box it is possible to activate the Auto-Top-Up for all future SIM orders by default. ## SIM Extension If your SIM cards are close to expiring, you will see an extra column in your SIM table called "Extendable". Three months before the end of your activation period you will be notified by e-mail and it will be visible in your SIM table which SIM cards can be extended. You can extend a single SIM card or filter for all extendable SIM cards. After selecting all relevant SIM cards, click on "Extend SIMs". You will be able to review your selected SIMs and the tariff details for the extension in the shopping cart. All of remaining data, SMS, and time will be transferred. The new activation period starts on the order day (when bank transfer is used, it starts as soon as the payment is received. After your expiry date has been reached you have 18 months to extend your SIM cards. The SIMs will not be usable in that transition period but you can extend them anytime. After 18 months the SIM cards will be irreversibly deleted.
![220824_SIM List_Extensionpng.png](/img/1nce-portal/portal-sims-sms/687f26f-220824_SIM_List_Extensionpng.png)
*SIM Extension* *** # SIM Detail Page By clicking on one of the SIMs in the list, a detailed view of the SIM status and configuration is shown. The top section of this view includes basics stats of the selected SIM. In the first column, the ICCID, IMSI, MSISDN and LABEL is shown. The LABEL field is editable and can help to assort the SIMs. The second column presents all lifetime data like time passed in %, the time left and the end date of the contract. The third column on the right shows all relevant network data, like the static IP-address, the IMEI of the connected device, the session-status, location of the device, the operator and the network bearer the SIM currently is attached to. ## SIM Configuration On the SIM detail page, the specific SIM can be (de-)activated, the IMEI lock set, Auto-Top-Up (de-)activated and additionally the SIM connection can be reset.
![1NCE_SIM_Details.PNG](/img/1nce-portal/portal-sims-sms/2b5c709fcd688db4f57134d5de1a9cceb4460cfe3cb683cd14ec382b8185cb18-CleanShot_2025-10-08_at_11.28.332x.png)
*Detail page of an example SIM Card.* ## Reset Connection By using "Reset Connection", the SIM is automatically deactivated and afterwards reactivated. This will force the SIM to disconnect from the current network operator and reattach. This feature is useful if the SIM is stuck in an unwanted connection. In the lower section, detailed logs of events and usage in chronological order are presented. Please note that this data is only retained for seven days due to the 1NCE data retention policy. The data in the Events tab is identical to the data found in the 1NCE Data Streamer. These events are very useful for debugging devices and seeing the current network events of a device. The Usage tab shows both the SMS and data usage of the last eight weeks, the available quota and the remaining volume for SMS and Data of this particular SIM. *** # SMS Console The SMS tab of the detailed SIM page can be used to exchange SMS messages with the device using the particular SIM. With the Source Address and Payload fields, a SMS can be prepared and send to the device. Please note that the device needs to be attached to a network in order to receive the message. In the table view below the sent SMS form, an overview of the Mobile Originated (MO) and Mobile Terminated (MT) SMS messages of the last seven days can be seen. To properly receive and process MT messages, review the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) guide. Besides the messages itself, the current status of the MO-/MT-SMS, the payload and type is listed. The list shows the type of SMS (MT or MO), the current status (Pending, OK, Failed), the timestamp the message was submitted and finally, the source address and the actual payload. Please note that MT-SMS will stay in the Pending state until the device has attached to the network and the message was delivered. For MO-SMS the state will remain in "pending" if no SMS Forwarding Service is setup as only this service will consume the SMS messages and properly acknowledge them. If a SMS message fails this is most likely due to reaching the delivery retry timeout. After a certain time of trying to deliver a message, the service will put the SMS into the failed state.
![1NCE_SMS_Console.png](/img/1nce-portal/portal-sims-sms/9ff2e66-1NCE_SMS_Console.png)
*Overview of the SMS Console.* --- # Users & Organisation Source: https://help.1nce.com/docs/1nce-portal/portal-users-organisations/ # User Management The 1NCE Customer Portal offers the option to create multiple user accounts which allows for different user roles and access rights. In the "User" tab a root owner of the account can create and edit new user accounts. A general overview of all current users of the 1NCE organization is provided in a list view.
![1NCE_User_List.PNG](/img/1nce-portal/portal-users-organisations/50d19d6-1NCE_User_List.PNG)
## User Roles The following roles for additional user accounts are available: | Role | Description | | --- | --- | | Owner | Initial user of the organization that cannot be changed. Includes all functionalities and access to the entire organization. New users can have the Owner role assigned as well. The owner also has access to the Management API. Can administer users with Admin, User, API User, Read Only, and 3rd party access role. *To administer Owner, please submit a service request.* | | Admin | Includes all functionalities and access to the entire organization. Can administer users with User, API User, Read Only, and 3rd party access role. This user role has no access the Management API. | | User | Can manage SIM Cards in the Portal, but has no access to orders and top-ups, and cannot trigger new orders or manage users. This user role has no access to the Mangement API. | | API User | User role only for accessing the 1NCE API. Uses client\_secret and client\_id as username and password for the API authentication. Has the account number as prefix in the client\_id. All endpoints are available for this role including new orders. | | Read Only | User role designed to allow Read-only access to the Portal. This user role has no access to the Mangement API. | | 3rd party access | User role designed for allowing 3rd Party Users limited access to the Portal. This user role has no access to the Mangement API. | ### User Roles Details See the following table for an exact overview of the roles and the permissions for each component of the 1NCE Portal.
Portal Areas Owner Admin User Read Only 3rd Party Access API User
Dashboard See All ✅ ✅ ✅ ✅ ✅ ❌
Reorder Button ✅ ✅ ❌ ❌ ❌
Latest Order Widget ✅ ✅ ✅ ✅ ❌
My SIMs See All ✅ ✅ ✅ ✅ ✅
SIM State ✅ ✅ ✅ ❌ ❌
IMEI Lock ✅ ✅ ✅ ❌ ❌
Auto-Top-Up ✅ ✅ ❌ ❌ ❌
Reset Connectivity ✅ ✅ ✅ ❌ ✅
SIM List Export ✅ ✅ ✅ ❌ ✅
Reorder / Top-Up ✅ ✅ ❌ ❌ ❌
Send SMS ✅ ✅ ✅ ❌ ✅
Configuration Network Settings ✅ ✅ ✅ ❌ ✅
Breakout Settings ✅ ✅ ❌ ❌ ✅
Monthly Limit ✅ ✅ ✅ ❌ ✅
IMEI Lock ✅ ✅ ✅ ❌ ❌
Auto-Top-Up ✅ ✅ ❌ ❌ ❌
Data Streams ✅ ✅ ❌ ❌ ✅
SMS Forwarder ✅ ✅ ✅ ❌ ✅
OpenVPN ✅ ✅ ✅ ❌ ✅
Management API ✅ ✅ ✅ ❌ ✅
1NCE OS Tab Available ✅ ✅ ✅ ✅ ✅
Account See All ✅ ✅ ✅ ✅ ✅
Customer Data ✅ ✅ ❌ ❌ ❌
User Data ✅ ✅ ✅ ✅ ✅
Add New E-Mail ✅ ✅ ❌ ❌ ❌
Billing and Shipping Address ✅ ✅ ❌ ❌ ❌
Payment Details ✅ ✅ ❌ ❌ ❌
Orders See All ✅ ✅ ✅ ✅ ❌
Download Invoices ✅ ✅ ✅ ✅ ❌
Trigger New Order ✅ ✅ ❌ ❌ ❌
Download Affected SIMs ✅ ✅ ✅ ✅ ❌
Users See All ✅ ✅ ✅ ✅ ✅
Administer Own User ✅ ✅ ✅ ✅ ✅
Administer Owner ❌ ❌ ❌ ❌ ❌
Administer Admin ✅ ❌ ❌ ❌ ❌
Administer User ✅ ✅ ❌ ❌ ❌
Administer API User ✅ ✅ ❌ ❌ ❌
Administer Read Only ✅ ✅ ❌ ❌ ❌
Administer 3rd party access ✅ ✅ ❌ ❌ ❌
Organisation See All ✅ ✅ ✅ ✅ ✅
Add Organisation ✅ ✅ ❌ ❌ ❌
SIM Transfer ✅ ✅ ❌ ❌ ❌
Performance See All ✅ ✅ ✅ ✅ ✅
Support See All ✅ ✅ ✅ ✅ ❌
New Service Request ✅ ✅ ✅ ❌ ❌
API Access ✅ ❌ ❌ ❌ ❌ ✅
## User Creation A new user can be created using the "New User" button on the top right. The mandatory details depend on the type of the user that needs to be created. The e-mail address is used for the confirmation of the account as well as the login name for the 1NCE services. Customers have to make sure that the entered e-mail address is valid and can receive messages. After creating a new user an e-mail is sent to the new mail address requesting to set an initial new password for the 1NCE Customer Portal.\ For the API role, the client\_id represents the username and the client\_secret the password. The client\_id has the account number with an underscore as prefix. The client\_secret needs to be set during the user creation as there is no e-mail address attached to this user role.
![1NCE_Add_User.png](/img/1nce-portal/portal-users-organisations/8a31386-1NCE_Add_User.png)
## User Account Alteration By clicking on a user shown in the list of current users, the details of this account can be changed or deleted. Changes can be applied by editing the boxes in the form and saving the new data. A user can be deleted by clicking on the "Delete" button in the Edit User popup.
![1NCE_User_Edit.png](/img/1nce-portal/portal-users-organisations/c710909-1NCE_User_Edit.png)
*** # Organization Management > ❗️ AWS Marketplace Accounts > > Please note that Organization Management is not available for AWS Marketplace accounts. In the "Organisation" tab, a list of all sub-organizations of the main 1NCE user account are shown and can be managed. This feature enables a customer to create independent organizations, e.g., for their subsidiary or sub-contractor.
![1NCE_Org_List.PNG](/img/1nce-portal/portal-users-organisations/9456a0d-1NCE_Org_List.PNG)
## Organisation Creation Creating a new organization requires the role Owner or Admin to be logged in. To create a new organization, users have to click on the "New Organisation" button in the top right corner of the page. The creation process of a new organization is structured in a few simple steps. All the required data have to be entered in the shown forms.
![1NCE_Org_Creation.png](/img/1nce-portal/portal-users-organisations/483feb5-1NCE_Org_Creation.png)
After validating the content summary and submitting the request, the new owner will be notified and asked to set up their password via e-mail, so that they can access the customer portal. Please note that the process of creating a sub-organization will not be finalized until the new owner has set the password.\ All existing features are active for the new organization. An order of SIM cards can be placed in the new organization by using the "Reorder" button on the dashboard and go through the regular ordering process. Alternatively, the master organization can order the SIM cards and transfer them to the sub-organization afterwards. The master organization can see the total number of SIMs ordered by each organization, but without having direct access unless a dedicated account has been created by the sub-org entity. ## Organization SIM Transfer If there are any sub-organizations, the "Organization" tab also offers the possibility to transfer SIMs from the master organization and vice versa. A direct transfer from sub- to sub-organization is not possible. The transfer of SIMs can also be done using the 1NCE API. Customers can transfer just one single SIM, a range of SIMs, or several ranges of SIMs. Here are some helpful tips for transferring several ranges: * The file with the ranges can either be .CSV or .TXT format * Single SIM ICCID, use the ICCID as Start- and End Range like “ICCID1;ICCID1” * Ensure no duplicate ICCID in the file as this will lead to errors in processing * Do not put a semicolon at the end of each line * There is no need to use quotation marks at all (not mandatory)
![230203_Organisations_SIM Transfer.PNG](/img/1nce-portal/portal-users-organisations/b0d5ae3-230203_Organisations_SIM_Transfer.PNG)
## Sub-Organization Deletion Sub-Organizations can be deleted directly from the portal. To delete an organization customers have to choose the respective sub-organization and click "Delete". A sub-organization can only be deleted after it is fully created and has no SIMs or open workflows running (e.g. open invoices or open SIM actions). --- # 1NCE VPN Linux Client Source: https://help.1nce.com/docs/blueprints-examples/1nce-vpn-linux-client/ ```powershell PowerShell > sudo apt install openvpn > sudo mv ./client.conf /etc/openvpn/client > sudo mv ./credentials.txt /etc/openvpn/client > sudo nano /etc/openvpn/client/client.conf auth-user-pass /etc/openvpn/client/credentials.txt > sudo systemctl start openvpn-client@client > sudo systemctl status openvpn-client@client openvpn-client@client.service - OpenVPN tunnel for 1nce_work Loaded: loaded (/lib/systemd/system/openvpn-client@.service; disabled; vendor preset: enabled) Active: active (running) since Mon 2021-07-05 14:26:42 CEST; 25s ago Docs: man:openvpn(8) https://community.openvpn.net/openvpn/wiki/Openvpn24ManPage https://community.openvpn.net/openvpn/wiki/HOWTO Main PID: 13170 (openvpn) Status: "Initialization Sequence Completed" Tasks: 1 (limit: 4915) CGroup: /system.slice/system-openvpn\x2dclient.slice/openvpn-client@client.service └─13170 /usr/sbin/openvpn --suppress-timestamps --nobind --config client.conf Jul 05 14:26:43 host openvpn[13170]: Initialization Sequence Completed > sudo systemctl stop openvpn-client@client > ifconfig inet 10.65.x.x netmask 255.255.255.255 destination 10.65.x.x inet6 x:x prefixlen 64 scopeid 0x20 RX packets 3078 bytes 193448 (188.9 KiB) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 2341 bytes 134700 (131.5 KiB) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 > route Destination Gateway Genmask Flags Metric Ref Use Iface ... 10.65.x.x 0.0.0.0 255.255.255.255 UH 0 0 0 tun0 100.97.x.x 10.65.x.x 255.255.255.0 UG 0 0 0 tun0 ... > ping x.x.x.x ``` # Requirements In this recipe, the setup and usage of the 1NCE VPN client with OpenVPN on a Linux OS (here Raspberry Pi OS) is shown. The configuration is done via the Command Line Interface (CLI). A Linux OS with CLI and Internet access is needed to follow this guide. # Download Configuration and Credentials As a first step, the 1NCE VPN configuration file for Linux OS needs to be downloaded from the 1NCE Portal. Please proceed to download the configuration and credential file and place them in an accessible folder on the Linux OS. # Install OpenVPN Open a CLI on the Linux OS. Install the current OpenVPN client for the used flavor of Linux OS. In this guide Raspberry Pi OS is used. The command for installing the OpenVPN client might differ dependent on the used OS flavor. Please wait until the VPN client is installed. # Configure OpenVPN Move the downloaded configuration and credential file to the OpenVPN folder. Dependent on the Linux OS, the exact target place might differ for the OpenVPN version. It is assumed that the downloaded files are in the currently selected folder. # Check Credentials Path Open the VPN configuration file and check that the location of the credentials file is set correctly that it matches the actual file location. # Start OpenVPN There are multiple ways how to start the OpenVPN client. In this guide, systemctl is used. Use the start command and the name of the configuration file to start the OpenVPN connection. # Monitor OpenVPN The current state of the connection can be viewed by querying the VPN client status. # Stop VPN Connection Similar to starting the VPN client, the connection can be stopped by the systemctl command with the stop option. # Monitor VPN Connection With ifconfig, the created tunnel interface details can be viewed. This will show the interface IP address and the transmitted VPN data volume. # Monitor IP Routes On VPN client connect, default routes will be added to the system to allow access to the customer 1NCE SIM pool. These routes can be listed and viewed. # ICMP Ping towards SIM To test the 1NCE VPN connection, a simple Ping towards an active device with a 1NCE SIM that is connected to the network and has a open PDP data session can be issued. Please note that the device needs to accept and response to Ping requests. Use the static IP of the device with the 1NCE SIM as destination for the Ping. # Wrap Up This recipe showed how to setup and use the 1NCE VPN to connect to IoT devices with a 1NCE SIM. --- # BG95-M3 1NCE OS UDP Source: https://help.1nce.com/docs/blueprints-examples/bg95-m3-1nce-os-udp/ ```powershell PowerShell /* connect to UDP server */ > AT+QIOPEN=1,0,"UDP","udp.os.1nce.com",4445,0,1 OK +QIOPEN: 0,0 > AT+QISEND=0 > Welcome to 1NCE OS SEND OK > AT+QICLOSE=0 OK ``` # Preparation Configure the BG95 module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # Open socket Use the AT+QIOPEN command to open a UDP socket and establish a connection with the remote server. # Send the message to 1NCEOS for Send After receiving ">", input data (TEST), the maximum length of the data is 1460, the data beyond 1460 will be omitted. Then use `` to send data. When receive SEND OK means the data has been sent # Close the Socket AT+QICLOSE command is used to close a socket connection established with a remote server using a TCP or UDP protocol. The command requires specifying the socket ID that was assigned when the connection was opened. --- # BG95-M3 ICMP Ping Source: https://help.1nce.com/docs/blueprints-examples/bg95-m3-icmp-ping/ ```powershell PowerShell > AT+CEREG? +CEREG: 0,5 > AT+CREG? +CREG: 0,5 > AT+CGREG? +CGREG: 0,4 > AT+CSQ +CSQ: 2,99 > AT+QICSGP=1,1,"iot.1nce.net","","",0 OK > AT+CGATT=1 OK > AT+CGPADDR +CGPADDR: 1,x.x.x.x OK > AT+QPING=1,"www.1nce.net",5 OK +QPING: 0,"15.197.142.173",32,459,255 +QPING: 0,"15.197.142.173",32,1312,255 +QPING: 0,"15.197.142.173",32,466,255 +QPING: 0,"15.197.142.173",32,449,255 +QPING: 0,4,4,0,449,1312,671 ``` # Preparation Open a serial terminal and connect to the BG95-M3 module using the AT command interface. # Network Registration Ensure that the module is registered to the cellular network if not check the recipe BG95-M3 Network registration # Check Signal Quality +CSQ: , is the received signal strength indication, expressed in dBm. The higher the value, the stronger the signal. is the channel bit error rate, expressed as a percentage. The lower the value, the better the channel quality. # Set the APN Set the Access Point Name (APN) for the network connection. # Activate the GPRS connection This command attaches the module to the GPRS network and activates the PDP context # Get IP Address This command retrieves the IP address assigned to the module by the network operator # ICMP Ping After the successful setup of the data session, with 'AT+QPING="www.1nce.net"' any URL or IP address can be pinged. The responses '+CIPPING: 0,"15.197.142.173",32,459,255 show the resolved IP address and the ping time. # Wrap Up This guide showed the basic setup of a BG95 with a 1NCE SIM to get an ICMP Ping request working. For more details and documentation please refer to the AT Command manual of the BG95. --- # BG95-M3 Network Registration Source: https://help.1nce.com/docs/blueprints-examples/bg95-m3-network-registration/ ```powershell PowerShell > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+QCCID +QCCID: xxxxxx8066602774xxxx > AT+COPS=? +COPS: (2,"Telekom.de","TDG","26201",9),(2,"Telekom.de","TDG","26201",9),(2,"Telekom.de","TDG","26201",9),,(0,1,2,3,4),(0,1,2) OK > AT+COPS=0 OK >AT+COPS=4,2,"26202" OK > AT+COPS=1,2,"26201" OK > AT+COPS? +COPS: 0,0,"Telekom.de",9 > AT+CEREG? +CEREG: 0,5 > AT+CREG? +CREG: 0,5 > AT+CGREG? +CGREG: 0,4 > AT+CSQ +CSQ: 2,99 > AT+COPS? +COPS: 0,0,"Telekom.de",9 > AT+QICSGP=1,1,"iot.1nce.net","","",0 OK > AT+QIACT? OK > AT+QIACT=1 OK > AT+QIACT? +QIACT: 1,1,1,"10.209.106.8" OK /* connect to UDP server */ > AT+QIOPEN=1,0,"UDP","udp.os.1nce.com",4445,0,1 OK +QIOPEN: 0,0 > AT+QISEND=0 > Welcome to 1NCE OS SEND OK ``` # Preparation For testing purposes, connect the BG95 to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # Check your ICCID The ICCID is a unique identifier that is assigned to every SIM card and is used to identify and authenticate the card with the mobile network. # PLMN Query Use 'AT+COPS=?' to query all Public Land Mobile Networks that can be received at the given location. Note this scan for operators can take some time to respond. In the returned result, all available network operators are listed with the long, short an numeric identifiers. # PLMN Automatic Selection To let the BG95 automatically choose which operator to connect to, issue 'AT+COPS=0'. This sets the registration process to automatic. # PLMN Manual/Automatic Selection Manual operator selection with a fallback to automatic is a good choice to ensure automatic failover in case of an outage. With 'AT+COPS=4,2,"26202"', manual/automatic mode (4) is selected and the numeric identifier setting (2) is used to set operator (26202). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Manual Selection Manual operator selection without a fallback to automatic is generally not recommended due to the missing failover in case of an outage. With 'AT+COPS=1,2,"26201"', manual mode (1) is selected and the numeric identifier setting (2) is used to set operator (26201). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Connection Process After setting a registration process with 'AT+COPS=...', the modem will try to connect to the Public Land Mobile Network. This can take some time to respond. Afterwards, the connection can be checked with 'AT+COPS?' and 'AT+CREG?' as usual. # Warm Up The BG95 can be configured for manual, automatic or manual/automatic network registration. For more details see the BG95 AT Command manual from the manufacturer. # Check Signal Quality +CSQ: ``,`` `` is the received signal strength indication, expressed in dBm. The higher the value, the stronger the signal. `` is the channel bit error rate, expressed as a percentage. The lower the value, the better the channel quality. # Check the network registration status The response to these commands indicates whether the module is registered with the network or not. # Check Network Operator This command returns the current operators and their status, and allows automatic network selection. # Set the APN Set the Access Point Name (APN) for the network connection. # 1NCE OS UDP To connect to the 1NCEOS network and send a UDP message using AT commands for Send After receiving ">", input data (TEST), the maximum length of the data is 1460, the data beyond 1460 will be omitted. Then use `` to send data. When receive SEND OK means the data has been sent --- # BG95&BG77 TCP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/bg95bg77-tcp-client-connection/ ```powershell PowerShell /* connect to TCP server */ > AT+QIOPEN=1,0,"TCP","", OK +QIOPEN: 0,0 +QIURC: "recv",0 > AT+QIRD=1 +QIRD: OK > AT+QISEND=0 > Welcome to 1NCE OS SEND OK > AT+QICLOSE=0 OK ``` # Start a TCP Connection A TCP connection towards a server with a given TCP port can be started with 'AT+QIOPEN=1,0,"TCP",'. The AT Command needs to list the TCP protocol, the target URL or IP and the used TCP Port. If the connection is successfully opened, '+QIOPEN: 0,0' is returned. # Receive TCP Data By default, the modem will indicate any incomming TCP data with '+QIURC: "recv",1'. The received data can be read by issuing the 'AT+QIRD=1' command. # Send TCP Data With 'AT+QISEND=1' the data send mode is activated. Any input send to the modem will be forwarded via the tcp connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the BG95. The modem will acknowledge the sent message # Close TCP Connection An active TCP connection can be closed with 'AT+QICLOSE=1'. The modem will close the TCP connection and respond with '+QIURC: "closed",1'. --- # EC25 & EC21 1NCE OS UDP Source: https://help.1nce.com/docs/blueprints-examples/ec25-ec21-1nce-os-udp/ ```powershell PowerShell AT+QIOPEN=1,1,"UDP","udp.os.1nce.com",4445 OK +QIOPEN: 1,0 AT+QISEND=1,17 > Welcome to 1NCEOS SEND OK AT+QICLOSE=1 OK ``` # Preparation Configure the EC25/EC21 module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # Open socket Use the AT+QIOPEN command to open a UDP socket and establish a connection with the remote server. # Send the message to 1NCEOS For Send After receiving ">", input data (TEST), the maximum length of the data is 1460, the data beyond 1460 will be omitted. Then use `` to send data. When receive SEND OK means the data has been sent, or you can specify number of Byte you want to send # Close the Socket AT+QICLOSE command is used to close a socket connection established with a remote server using a TCP or UDP protocol. The command requires specifying the socket ID that was assigned when the connection was opened. --- # EC25 ICMP Ping Source: https://help.1nce.com/docs/blueprints-examples/ec25-icmp-ping/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",7 OK > AT+CGDCONT=1,"IP","iot.1nce.net" OK > AT+CGACT=1,1 OK > AT+CGPADDR=1 +CGPADDR: 1,"10.37.41.5" OK > AT+QPING=1,"8.8.8.8",1,4 OK +QPING: 0,"8.8.8.8",32,468,255 +QPING: 0,"8.8.8.8",32,138,255 +QPING: 0,"8.8.8.8",32,178,255 +QPING: 0,"8.8.8.8",32,121,255 +QPING: 0,4,4,0,121,468,226 > AT+CGACT=0,1 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the EC25 and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CGDCONT=1,"IP","iot.1nce.net"' command the 1NCE APN can be set. # Start PDP Session With 'AT+CGACT=1,1' the PDP session for CID one is started. A PDP data session is needed to transfer any sort of data. # Get IP Address With 'AT+CGPADDR=1' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # ICMP Ping After the successful setup of the data session, with 'AT+QPING=1,"8.8.8.8",1,4' any URL or IP address can be pinged. The responses '+QPING: 0,"8.8.8.8",32,468,255' show the resolved IP address and the ping time. # Data Session Close With 'AT+CGACT=0,1' the entire PDP data session of the modem is closed. # Wrap Up This guide showed the basic setup of a EC25 with a 1NCE SIM to get an ICMP Ping request working. For more details and documentation please refer to the AT Command manual of the EC25. --- # EC25 MO-SMS Source: https://help.1nce.com/docs/blueprints-examples/ec25-mo-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",7 OK > AT+CMGF=1 OK > AT+CSCS="GSM" OK > AT+CMGS="+49123456" > Test SMS > 1A // HEX-Encoded followed by Newline +CMGS: 25 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the EC25 and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Select SMS Format Specify the SMS format to 'Text Mode' using 'AT+CMGF=1' # Start MO-SMS Message Start the MO-SMS message by calling 'AT+CMGS="+49123456". This will start the SMS text mode to send a message. The target phonenumber can be left empty or filled with any number. The 1NCE SMS Service ignores this number and forwards the SMS via the SMS Forwarder. The command will not return an OK response, it waits for the message input. # Write MO-SMS Message The modem is now in the text mode an will accept ASCII Numeric values for the SMS. It will not return any response until the message is finished. Please keep the SMS size limitations in mind. # Finish MO-SMS Message To finish, exit the text mode and send the SMS message, '1a' needs to be send encoded as HEX towards the modem. The modem will respond with '+CMGS: ``' and an OK if successful. # Wrap Up The MO-SMS was sent and can be received with the 1NCE SMS Forwarding service or viewed in the 1NCE Portal. --- # EC25 MT-SMS Source: https://help.1nce.com/docs/blueprints-examples/ec25-mt-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",7 OK > AT+CMGL="ALL" +CMGL: 1,"REC UNREAD","123","","21/06/22,10:13:29+00" MT-SMS 01 Test +CMGL: 2,"REC UNREAD","123","","21/06/22,10:13:45+00" MT-SMS 02 OK > AT+CMGR=1,0 +CMGR: "REC READ","123","","21/06/22,10:13:29+00" MT-SMS 01 Test OK > AT+CMGD=1,0 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the EC25 and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Issue MT-SMS A SMS destined for a specifc device with a 1NCE SIM can be send using the Connectivity Management Platform website or through an API call. See the Developer Hub Guide for how to issue a MT-SMS. A SMS can be send while the device is not connected to the network. It will be delivered and received as soon as the device reconnects to the network. In this example, the source address was '123'. # Receive MT-SMS After connecting to the network, wait until the issued MT-SMS is received by the device. # Read All MT-SMS All SMS messages stored can be listed through 'AT+CMGL="ALL"'. The 'ALL' parameter can be changed according to the AT Command manual. # Read Specific MT-SMS One specific MT-SMS can be read using 'AT+CMGR=``,0', where the `` is the storage id of the message of interest. # Delete Specific MT-SMS Stored SMS messages can be deleted using 'AT+CMGD=``,0' # Wrap Up MT-SMS messages issued through the API of 1NCE portal, received by the EC25 can be read using a few simple AT Commands. Setting up the APN is not required for using SMS. --- # EC25 Network Registration Source: https://help.1nce.com/docs/blueprints-examples/ec25-network-registration/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+COPS=? +COPS: (1,"Telekom.de","TDG","26201",0),(1,"o2 - de","o2 - de","26203",0),(1,"Vodafone.de","Vodafone","26202",0),(1,"o2 - de","o2 - de","26203",2),(1,"o2 - de","o2 - de","26203",7),(2,"Telekom.de","TDG","26201",7),,(0-4),(0-2) OK > AT+COPS=0,0 OK > AT+COPS=4,2,"26202" OK > AT+COPS=1,2,"26201" OK > AT+COPS? +COPS: 1,2,"26201",7 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS=3,0 OK > AT+COPS? +COPS: 1,0,"Telekom.de 1nce.net",0 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Query Use 'AT+COPS=?' to query all Public Land Mobile Networks that can be received with the EC25 at the given location. Note this scan for operators can take some time to respond. In the returned result, all avaliable network operators are listed with the long, short an numeric identifiers and avaliable Radio Access Technologies. # PLMN Automatic Selection To let the EC25 automatically choose which operator to connect to, issue 'AT+COPS=0,0'. This sets the registration process to automatic. The preferred RAT selection will still apply. # PLMN Manual/Automatic Selection Manual operator selection with a fallback to automatic is a good choice to ensure automatic failover in case of an outage. With 'AT+COPS=4,2,"26202"', manual/automatic mode (4) is selected and the numeric identifier setting (2) is used to set operator (26202). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Manual Selection Manual operator selection without a fallback to automatic is generally not recommended due to the missing failover in case of an outage. With 'AT+COPS=1,2,"26201"', manual mode (1) is selected and the numeric identifier setting (2) is used to set operator (26201). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Connection Process After setting a registration process with 'AT+COPS=...', the modem will try to connect to the Public Land Mobile Network. This can take some time to respond with 'OK'. Afterwards, the connection can be checked with 'AT+COPS?', 'AT+CREG?' and 'AT+CGREG?' specific for GSM or 'AT+CEREG?' for LTE. # PLMN Format Selection The format of the current operator listing returned by 'AT+COPS?' can be set with 'AT+COPS=3,``'. Valid formats are (0) long, (1) short, (2) numeric. # Wrap Up The EC25 can be configured for manual, automatic or manual/automatic network registration. For more details and options see the EC25 AT Command manual from the manufacturer. --- # EC25 RAT Configuration Source: https://help.1nce.com/docs/blueprints-examples/ec25-rat-configuration/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+QCFG="gprsattach" +QCFG: "gprsattach",1 OK > AT+QCFG="gprsattach",1 OK > AT+QCFG="nwscanmode" +QCFG: "nwscanmode",0 OK > AT+QCFG="nwscanmode",0 OK > AT+QCFG="nwscanseq" +QCFG: "nwscanseq",0301020405 OK > AT+QCFG="nwscanseq",00 OK > AT+QCFG="roamservice" +QCFG: "roamservice",255 OK > AT+QCFG="roamservice",2 OK > AT+CFUN=0 OK > AT+CFUN=1 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # GPRS Attach Behavior Upon power on boot, the device can be configured to automatically connect to the mobile network. Using 'AT+QCFG="gprsattach"' the current setting can be queried. Setting the default behavior to 'AT+QCFG="gprsattach",1' will enable automatic network connect upon boot. # Network Scan Behavior Using 'AT+QCFG="nwscanmode",0' the Radio Access Technology (RAT) which will be used to scan for networks to attach to can be set. We recommend to set this paramter to '0' to enable 'Auto' search for all RATs. # Network Scan Sequence The search sequence for the different RATs can be defined with 'AT+QCFG="nwscanseq",00'. '00' indicates the 'Automatic' setting. Specific orders can be set by appending the RAT codes (e.g., 0401 - LTE - GSM). # Roam Service For a 1NCE SIM the roam service needs to be enabled with 'AT+QCFG="roamservice",2'. # Restart Modem Functionality For all settings to apply, please restart the modem functionality using 'AT+CFUN=0' and then 'AT+CFUN=1'. # Wrap Up This guide showed the basic setup of a Quectel EC25 with a 1NCE SIM. For more details and documentation please refer to the AT Command manual of the EC25. --- # EC25 TCP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/ec25-tcp-client-connection/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",7 OK > AT+CGDCONT=1,"IP","iot.1nce.net" OK > AT+CGACT=1,1 OK > AT+CGPADDR=1 +CGPADDR: 1,"" OK > AT+QIOPEN=1,1,"TCP","", OK +QIOPEN: 1,0 +QIURC: "recv",1 > AT+QIRD=1 +QIRD: OK > AT+QISEND=1 > > 1a AT+QICLOSE=1 +QIURC: "closed",1 OK AT+CGACT=0,1 OK ``` # Preperation For testing purposes, connect the EC25 (EC25EFAR06A08M4G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the EC25 and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CGDCONT=1,"IP","iot.1nce.net"' command the 1NCE APN needs to be set. # Start PDP Session With 'AT+CGACT=1,1' the PDP Session is started. # Get IP Address With 'AT+CGPADDR=1' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # Start a TCP Connection A TCP connection towards a server with a given TCP port can be started with 'AT+QIOPEN=1,1,"TCP",'. The AT Command needs to list the TCP protocol, the target URL or IP and the used TCP Port. If the connection is successfully opened, '+QIOPEN: 1,0' is returned. # Receive TCP Data By default, the modem will indicate any incomming TCP data with '+QIURC: "recv",1'. The received data can be read by issuing the 'AT+QIRD=1' command. # Send TCP Data With 'AT+QISEND=1' the data send mode is activated. Any input send to the modem will be forwarded via the tcp connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the EC25. The modem will acknowledge the sent message. # Close TCP Connection An active TCP connection can be closed with 'AT+QICLOSE=1'. The modem will close the TCP connection and respond with '+QIURC: "closed",1'. # Close Data Session To close the entire data session 'AT+CGACT=0,1' needs to be used. Afterwards a new session can be started at any point. # Wrap Up This guide showed the basic setup of a EC25 with a 1NCE SIM to send and receive data using a TCP connection. For more details and documentation please refer to the AT Command manual of the EC25. --- # Data Streamer Service Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/ The 1NCE Data Streamer offers multiple integration possibilities. For each of the available integrations 1NCE provides a setup guide and examples for testing. Please click on one of the icons to get to the setup guide for the selected integration.
![](/img/blueprints-examples/examples-data-streamer/d47972b-rest_api.svg)
--- # DataDog Integration Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/001.png)
DataDog is a cloud monitoring service that can be used to monitor the endpoint volume (Usage records) of the 1NCE SIM cards using custom dashboards and trigger events. The following metrics can be viewed in DataDog: endpoint.volume, endpoint.volume\_tx, endpoint.volume\_rx, and endpoint.cost. *** # DataDog Data Streamer Setup For the DataDog Data Streamer configuration, a account with a new API Key needs to be setup. Afterwards, the Data Streamer integration in the 1NCE Portal can be setup. The incoming usage records can be seen on the DataDog Metrics Explorer. Follow these steps to obtain the needed parameters for the 1NCE Portal configuration. > 📘 DataDog Regions > > Please note that only the DataDog Account Regions US, US3, EU, US1FED are available for the 1NCE Data Streamer integration. 1. Setup a **DataDog Account** in one of the supported regions. 2. Go to the **Organization Settings** on the main screen by clicking on the **User Profile**. 3. Select **API Keys** from the settings menu. 4. Click **New Key** in the top right to create a new API Key.
![DataDog_Configuration_01.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/b1e2c9f-DataDog_Configuration_01.png)
5. Provide a **Name** for the API Key. 6. Click **Generate Key** to issue a new API Key.
![DataDog_Configuration_02.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/392dfc2-DataDog_Configuration_02.png)
7. The next window will show the **Key ID** and the **API Key**. 8. The Key ID is a unique identifier for the API Key and should not be confused with the actual (API) Key. 9. Click **Copy Key** to copy the API Key.
![DataDog_Configuration_03.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/e5f5329-DataDog_Configuration_03.png)
10. On the overview page, all API Keys are listed. By clicking on a Key, details of the specific API Key are shown. 11. From there the API Key can be copied or revoked.
![DataDog_Configuration_04.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/1f3d255-DataDog_Configuration_04.png)
12. Copy & Paste the **API Key** to the configuration in the 1NCE Portal. 13. Once setup in the 1NCE Portal, the Usage records of all 1NCE SIMs of the used organization will be provided to DataDog. 14. Go to **Metrics > Summary** of the DataDog project to see the available streams. Please note, SIMs need to generate some recent usage events to make the DataDog integration appear for the first time.
![DataDog_Configuration_05.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/85f1650-DataDog_Configuration_05.png)
*** # 1NCE Portal DataDog Configuration For setting up a DataDog Data Streamer integration in the 1NCE Portal, the DataDog API Key and the Region of the used DataDog Account is needed. As Stream Type only Usage Data should be used as Event records are not supported by DataDog. * **API Type:** Select DataDog to customize the settings. * **Stream Type:** Choose *Usage Data* records as Events are not supported in DataDog. * **Name:** Identification name used in the Connectivity Management Platform for labeling the specific integration. * **API Key:** The API Key created in the DataDog settings. * **Region:** Region of the DataDog Account. * Click **Save** to create the Data Streamer integration.
![datadog_integration_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/a6cdbb1-datadog_integration_cmp.png)
*** # DataDog Streamer Testing For testing a DataDog integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Usage records. Please note that DataDog only supports Usage Records. Therefore, the Data Service has to be used to generate some usage. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the Usage records the following procedures can be executed: * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data volume has been actively used. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. ## DataDog Results The incoming events in DataDog can be viewed in the Metrics Summary. All Usage Records of the 1NCE SIMs in the organization account will be forwarded to DataDog.
![DataDog_Configuration_05.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/4537f00-DataDog_Configuration_05.png)
--- # HTTP/Webhook Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/examples-data-streamer-http/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-http/001.png)
The HTTP/Webhook integration of the Data Streamer is ideal for custom server applications. This method offers the most flexible, custom integration of the Data Streamer Service into existing analytics, reporting, and monitoring pipelines. The Http callbacks supports both Event and Usage Records. # General HTTP Interface The HTTP endpoints needs to handle Posts requests with a Body containing a list of JSON objects. A maximum of 3.000 JSON object records per sent HTTP Post request can be expected. If data is available, the requests are sent in a regular interval. The customer supplied endpoint should consume the HTTP Post with a HTTP 200 status code response. Acknowledged records will not be resend again. The streamer service does not respond to HTTP redirect codes (3xx). A HTTP Basic Authentication Header must be configured in the 1NCE Portal for this Data Streamer type. ## Endpoint URL The provided endpoint URL in the 1NCE Portal Configuration needs to be valid. URLs with public IP addresses (`https://://`) are not supported. Custom ports for the endpoint can be configured via the URL (`https://://`). ## Certificate The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using [Let's Encrypt](https://letsencrypt.org/de/) certificates. ## Endpoint Capacity Be aware that the HTTP/Webhook integration will deliver the incoming events as a list of JSON objects. Dependent on the amount of SIMs and occurred records this request can be quite large. A maximum limit of 3.000 records per request is set. 1NCE customers with a large quantity of SIMs and high number of events as such must be aware that their backend system receiving data from the stream needs to have the capacity to handle large incoming requests. *** # 1NCE Portal Configuration After implementing a HTTP Post endpoint on a custom backend, the Data Streamer needs to be configured in the 1NCE Portal in the Configuration tab. For a complete Data Stream setup using HTTP/Webhook, two configurations (Events and Usage) need to be created in the 1NCE Portal. Still, the same endpoint could be used as target for both stream setups. After the configuration the SIM Event and Usage Records will be forwarded to the specified customer endpoint. 1. **API Type:** Select RestAPI to customize the settings. 2. **Stream Type:** Choose between Usage Data and Event Data records. If both record types are desired, two separate Data Streams with the same destination endpoint can be setup. 3. **Name:** Identification name used in the Connectivity Management Platform for labeling the specific integration. 4. **API Callback:** URL to the customer provided HTTPs endpoint accepting the HTTP POST requests. * The endpoint URL for the Data Streamer in the needs to be valid. * Public IP addresses (`https://"server-ip":"port"/"endpoint"/`) are not supported. * Custom ports for the endpoint can be configured via the URL (`https://"server-domain":"port"/"endpoint"/`). * The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using Let's Encrypt certificates. 5. **Basic Auth Header:** Base64 encoded value supplied by each HTTP POST request in the Basic Authentication Header field. The supplied HTTP endpoint needs to support Basic Authentication. 6. Click **Save** to create the Data Streamer integration. ![data-streamer-webhook.jpg](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-http/8a6a25f-data-streamer-webhook.jpg) *** # HTTP/Webhook Integration Testing Testing a Data Streamer integration can be done in two ways: using a 1NCE SIM in a device or sample HTTP cURL requests. This sections explains the two ways of testing the Data Streamer integration. ## 1NCE SIM Device For simple testing with a 1NCE SIM, we recommend to use a smartphone or manually controllable IoT device. 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. After the device has attached to the network, see mobile network status indicator on the smartphone, a couple of first events should show up in the Data Streamer. 4. To generate Usage Records, create a data session and use some data traffic or Alternatively send some MT/MO-SMS. Note that data session usage is only recorded after a session has been closed. For smartphone testing simply disable data roaming or airplane mode to simulate the closing of the data session. 5. Check the Usage Record integration. After some time, the used data volume and/or SMS volume record will be provided. ## Simulated Events and Usage Records To simulate HTTP/Webhook events, simple HTTP Post cURL requests with JSON List Body messages can be posted to the custom endpoints. Below two examples for an Event and Usage Record cURL can be found. Please adapt the endpoint URL to the server URL used for integration. Use Postman or Command Line Interface (CLI) to issue these example requests. The data should be received by the customer-side implemented Data Streamer receiver.
Update Location Event cURL ```curl Update Location HTTP Post cURL curl --location --request POST 'https://://' \ --header 'Content-Type: application/json' \ --data-raw '[{ "imsi": { "imsi": "", "id": 123456, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from VLR for IMSI='', now attached to VLR=''.", "alert": false, "id": 1234567890, "user": null, "detail": { "mnc": [ { "mnc": "20", "id": 327 }, { "mnc": "16", "id": 328 } ], "tapcode": [ { "tapcode": "NLDDT", "id": 470 }, { "tapcode": "NLDPN", "id": 471 } ], "name": "T-Mobile", "country": { "iso_code": "nl", "country_code": "31", "name": "Netherlands", "id": 141, "mcc": "204" }, "id": 730 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 1, "description": "Update location" }, "timestamp": "2019-01-21T09:36:17Z" }]' ```
Usage Record cURL ```curl Usage Record HTTP Post cURL curl --location --request POST 'https://://' \ --header 'Content-Type: application/json' \ --data-raw '[{ "imsi": "", "organisation": { "name": "8100xxxx", "id": 1234 }, "start_timestamp": "2021-08-09T12:59:05Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "id": 2, "name": "T-Mobile", "mnc": "01", "country": { "id": 74, "mcc": "262", "name": "Germany" } }, "tariff": { "ratezone": { "name": "Rate Zone 2 (EU - DE)", "id": 2067 }, "name": "1NCE Production 01", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "Data", "id": 5 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678, "balance": null }, "cost": 0.001176, "volume": { "total": 0.001176, "tx": 0.001176, "rx": 0.0 } }]' ```
### Postman Mock Server A good way to start with the 1NCE Data Streamer is a [Postman Mock Server](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/). A mock server can be setup fast without any need of external infrastructure. Simply create a HTPP Post endpoint with a given name and provide the mock server URL and the chosen Endpoint name in the 1NCE Portal Data Streamer configuration. Afterwards, the Data Streamer events should be sent to the mock server. The mock server allows to inspect real network events triggered by the SIMs and organization of the customer. Further, using Postman, the CURL demo events can be sent either to the mock server or the customer server implementation. --- # Keen.io Integration Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/001.png)
The Keen.io platform is a managed event streaming platform used for streaming, analyzing, and embedding rich data. The 1NCE Data Streamer Service can easily be integrated with this service. The Keen.io integration supports both Event and Usage Records.\ These chapters guides through the initial setup of the Keen.io project, 1NCE Portal Data Streamer configuration and a guide to testing the Keen.io integration. *** # Keen.io Data Streamer Configuration For the Keen.io configuration, a account with a new project needs to be setup. Afterwards, the Data Streamer integration in the 1NCE Portal can be setup. The incoming data can be seen on the Keen.io streams tab. Follow these steps to obtain the needed parameters. 1. Set up an active Keen.io account or use an existing instance. 2. Create a new project within the Keen.io account. 3. Open the project page and go to the **Access Tab** to obtain the **Project ID** and **Write Key** from the newly created project. ![keen_access.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/9a5fec6-keen_access.png) 5. Copy & Paste the **Project ID** and **Write Key** to the configuration in the 1NCE Portal. 6. Once setup in the 1NCE Portal, the Event or Usage records of all 1NCE SIMs of the used organization will be provided as Keen.io Streams. 7. Go to the **Streams Tab** of the Keen.io project to see the available streams as a list in the Event Streams window. Please note, SIMs need to generate some recent events to make the Keen.io streams appear for the first time. This may take a while.\ 8.Once the stream integrations show up, the advanced features of Keen.io can be used to create custom Dashboards and Monitoring. ![keen_stream.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/8b017aa-keen_stream.png) *** # 1NCE Portal Keen.io Configuration After setting up a Keen.io project for the Data Streamer integration, the related parameters need to be configured in the 1NCE Portal. Please note that if both Usage and Event records should be obtained using Keen.io, 1NCE recommends to use two separate project integrations, one for each streamer type. The following parameters need to be setup in the 1NCE Portal. 1. **API Type:** Select keen.io to customize the settings. 2. **Stream Type:** Choose between *Usage Data* and *Event Data* records. If both record types are desired, two separate Data Streams with the different Keen.io projects can be setup. 3. **Name:** Identification name used in the 1NCE Portal for labeling the specific integration. 4. **Project Key:** The Keen.io Project Key from the newly created project integration. 5. **Write Key:** Write Key from the newly created Keen.io project. 6. **Collection Name:** Name of the collection created in the Kenn.io project. 7. Click **Save** to create the Data Streamer integration. ![keen_integration_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/08497b5-keen_integration_cmp.png) *** # Keen.io Data Streamer Testing For testing a Keen.io integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # Keen.io Results The incoming events in Keen.io can be viewed in the Streams Tab. Dependent on the configuration, for each received Data Streamer Event and Usage record the raw JSON data can be viewed. ![keen_stream.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/2553597-keen_stream.png) --- # AWS Kinesis Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/001.png)
The 1NCE Data Streamer Service can be integrated with AWS Kinesis which is ideal for collecting and processing large streamed data records in near real-time. AWS Kinesis are integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the 1NCE Portal. The following subchapters explain the Cloud Formation and 1NCE Portal setup as well as some testing procedures. *** # AWS Kinesis Configuration To setup the 1NCE Data Streamer integration with AWS Kinesis, it is recommended to use the Cloud Formation Template provided in the 1NCE Portal. As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. After completing the steps, the selected record type should show up in the AWS Kinesis Stream bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. 1. Open the 1NCE Portal and navigate to *Configuration-Data Streams-Add New Data Stream*. 2. In the popup select AWS Kinesis as **API Type** and select the desired **Stream Type**. 3. Click on **Create IAM Role** to open the Cloud Formation Template in a separate window. ![aws_kinesis_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/049665e-aws_kinesis_cmp.png) 4. Adapt the CFN Template parameters (Stack Name, KinesisStreamName). Do NOT change AllowedExternalID and DatastreamerRoleARN. 5. Set the **IAM Creation** checkbox. 6. Execute the CFN Stack by clicking on **Create Stack**. ![aws_kinesis_cfn.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/5969b1e-aws_kinesis_cfn.png) 7. Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/1d364db-aws_cfn_done.png) 8. Go to the **Outputs** tab of the created CFN Stack. 9. Copy the shown parameters to the popup in the 1NCE Portal. 10. Click on **Save** in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_kinesis_cfn_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/19d3af3-aws_kinesis_cfn_cmp.png) *** # Testing AWS Kinesis Data Streamer For testing a AWS Kinesis integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. After the device has attached to the network, see mobile network status indicator on the smartphone- 4. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # AWS Kinesis Results Dependent on the Data Streamer configuration the AWS Kinesis Stream will contain Event and Usage data. The data is received as JSON Objects.\ From the AWS Kinesis Stream the received data can be processed using available AWS processing tools. --- # AWS S3 Bucket Source: https://help.1nce.com/docs/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/001.png)
The 1NCE Data Streamer Service can be integrated with AWS S3 which is an object-based storage solution. The Data Streamer can push CSV files into a S3 bucket allowing for easy, largescale data collection and further processing later on by related AWS Services. AWS S3 is integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the 1NCE Portal. *** # S3 Filename and Data Format The S3 integration will provide the Event or Usage Records through an S3 bucket where they are uploaded as CSV files. The CSV filenames for events are "events\_YYYYMMDD\_HHmmss.csv" and "cdr\_YYYYMMDD\_HHmmss.csv" for usage records. Each file contains a collection records over a small period. A sample for an event record file type is provided below. ```text cdr_20210512_070123.csv "id","event_start_timestamp","event_stop_timestamp","organisation_id","organisation_name","endpoint_id","sim_id","iccid","imsi","operator_id","operator_name","country_id","operator_country_name","traffic_type_id","traffic_type_description","volume","volume_tx","volume_rx","cost","currency_id","currency_code","currency_symbol","ratezone_tariff_id","ratezone_tariff_name","ratezone_id","ratezone_name","endpoint_name","endpoint_ip_address","endpoint_tags","endpoint_imei","msisdn_msisdn","sim_production_date","operator_mncs","country_mcc" "4427264xxx","2021-05-11 11:17:25","2021-05-11 11:19:51","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.000741","0.000395","0.000346","0.0007410000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" "4427320xxx","2021-05-11 11:17:29","2021-05-11 11:24:56","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.003210","0.001803","0.001407","0.0032100000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" ``` *** # AWS S3 Configuration The easiest setup for the stream integration into AWS S3 is by using the Cloud Formation Template via the 1NCE Portal. As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. After completing the steps, the selected record type should show up in the AWS S3 bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. 1. Open the Portal and navigate to *Configuration-Data Streams-Add New Data Stream*. 2. In the popup select AWS S3 as **API Type** and select the desired **Stream Type**. 3. Click on **Create IAM Role** to open the Cloud Formation Template in a separate window. ![aws_s3_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/05fc0c9-aws_s3_cmp.png) 4. Adapt the CFN Template parameters (Stack Name, S3BucketName). Do NOT change AllowedExternalID and DatastreamerRoleARN. 5. Set the **IAM Creation** checkbox. 6. Execute the CFN Stack by clicking on **Create Stack**. ![aws_s3_cfn.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/a776ebd-aws_s3_cfn.png) 7. Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/90d26f6-aws_cfn_done.png) 8. Go to the **Outputs** tab of the created CFN Stack.\ 9 Copy the shown parameters to the popup in the 1NCE Portal. 9. Click on **Save** in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_s3_cfn_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/c246722-aws_s3_cfn_cmp.png) *** # Testing AWS S3 Data Streamer For testing an AWS S3 integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # AWS S3 Results Dependent on the Data Streamer configuration the S3 bucket will be filled with CSV files. These CSV files include the Event or Usage record data from the Data Stream. The CSV filenames for events are "events\_YYYYMMDD\_HHmmss.csv" and "cdr\_YYYYMMDD\_HHmmss.csv" for usage records. Each file contains a collection records over a small period. From the S3 bucket the received data can be processed using available AWS processing tools. --- # Hardware & Modem Guides Source: https://help.1nce.com/docs/blueprints-examples/examples-hardware-guides/ --- # Examples Overview Source: https://help.1nce.com/docs/blueprints-examples/examples-overview/ Often an example helps getting started with a new service integration. As addition to the documentation of the 1NCE Services in the Developer Hub, this sections provides real use case examples for these services. Find an overview of the current examples available below. We are continuously working on improving and extending the given examples. If you have feedback, questions or recommendations, feel free to reach out to us. - [Hardware & Modems](/docs/blueprints-examples/recipes/) — Modems, GPS tracker, IoT router or custom hardware getting started with 1NCE connectivity is very easy with most devices. We provide some guides to showcase common setups. - [SMS Services](/docs/blueprints-examples/examples-sms/) — Sending and receiving MO-/MT-SMS with 1NCE Connectivity, these guides show common examples to get started with SMS messaging. - [SMS Forwarder](/docs/blueprints-examples/examples-sms-forwarder/) — Setup of the SMS Forwarder using the Webhook integration. Examples for testing and debugging the Forwarder Service. - [Data Streamer](/docs/blueprints-examples/examples-data-streamer/) — From AWS to Keen.io, DataDog or Webhook integration, these setup guides for all types of Data Streamer integrations provide an easy starting point to receive, process, and analyze Event and Usage Records from 1NCE SIMs. - [VPN Integration](/docs/blueprints-examples/examples-vpn/) — Bidirectional connectivity establishment is available through the 1NCE VPN Service. We provide guides for installing the 1NCE VPN integration and instructions for basic testing, debugging and common use cases. - [More to come...]() — We are working on providing more and extended examples for getting started with 1NCE Services. --- # SMS Forwarder Service Source: https://help.1nce.com/docs/blueprints-examples/examples-sms-forwarder/
![](/img/blueprints-examples/examples-sms-forwarder/001.png)
With the SMS Forwarding Service, Mobile Originated SMS (MO-SMS) messages and Delivery Reports (DLR) for Mobile Terminated SMS (MT-SMS) are forwarded to a customer-specified HTTP REST endpoint as JSON objects. This example section will outline the general requirements for the HTTP endpoint and provide guides for the configuration and implementation. *** # REST Interface The receiving server needs to provide a REST Interface, which accepts HTTP Post/Patch requests issued from the 1NCE SMS Forwarding Service. MO-SMS from a SIM device are issued using HTTP Post. For MT-SMS towards a SIM device, Delivery Reports are issued with HTTP Patch requests. The server should reply with a HTTP 200 status code. This indicates that the forwarded SMS event was received and will not be repeated afterwards. In case another HTTP status code is returned, the SMS event will be repeated until it is successfully received or a 24-hour timeout is reached. ## Endpoint URL The endpoint URL for receiving SMS messages configured in the 1NCE Portal Configuration needs to be valid. URLs with public IP addresses (`https://://`) are not supported. Custom ports for the endpoint can be configured via the URL (`https://://`). ## Certificate The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. 1NCE recommends using [Let's Encrypt](https://letsencrypt.org/de/) certificates. ## Warnings & Errors A warning event record (e.g., HTTP 500) is written in the Data Streamer and 1NCE Portal SIM Event Log if an event delivery to the specified server was unsuccessful. In this case, verify that the endpoint is reachable and returns HTTP 200 to the incoming HTTP Post/HTTP Patch request. *** # SMS Forwarder Sequence Diagrams The two sequence diagrams below show the MT-SMS DLR and the MO-SMS delivery using the SMS Forwarding Service. These diagrams provide a basic overview of the working principle of the SMS Forwarding Service. ## MO-SMS Delivery The figure shows a successful and failed flow of an MO-SMS delivery using the SMS Forwarder. The MO-SMS is always provided via the 1NCE Portal and the 1NCE API. The status of a MO-SMS can be queried in the Portal and the API. The delivery failed error message is delivered via the Data Streamer and also shown in the 1NCE Portal.
![](/img/blueprints-examples/examples-sms-forwarder/002.png)
## MT-SMS DLR The figure below shows the flow of a Delivery Report for a MT-SMS. Once a mobile terminated SMS is issued via the API or 1NCE Portal, it will be delivered to the SIM device. Once received by the device, a delivery report (DLR) is issued from the 1NCE network using the SMS Forwarder webhook integration. The DLR indicates that the SMS was delivered to the targeted SIM device. If no webhook / HTTP endpoint is configured, the delivery of the DLR will fail resulting in an event shown in the data streamer and 1NCE Portal.
![](/img/blueprints-examples/examples-sms-forwarder/003.png)
--- # 1NCE Portal Configuration Source: https://help.1nce.com/docs/blueprints-examples/examples-sms-forwarder/examples-sms-forwarder-portal/ The SMS Forwarder settings can be found in the 1NCE Portal within the Configuration Tab. To receive the MO/MT-SMS events from the SMS Forwarder, a custom endpoint URL (`https://://`) of the receiving server needs to be configured in the 1NCE Portal. Custom ports for the endpoint can be configured via `https://://`. Once the settings have been saved, the MO-SMS and DLR will be forwarded to the provided server URL. The configured endpoint can be edited at any point. To delete the configuration just leave the URL field empty and save the configuration. ![1NCE_SMS_Forwarder.PNG](/img/blueprints-examples/examples-sms-forwarder/examples-sms-forwarder-portal/a4ae561-1NCE_SMS_Forwarder.PNG) --- # Testing SMS Forwarder Source: https://help.1nce.com/docs/blueprints-examples/examples-sms-forwarder/examples-sms-forwarder-testing/ Before deploying a custom integration into production, testing is usually carried out. For testing the 1NCE SMS Forwarding Service with MT-SMS Delivery Reports and MO-SMS messages, real SIM device SMS events or simulated HTTP Post/Patch requests can be used. *** # SIM Event Testing When testing with real SMS events, an active 1NCE SIM in a device capable of sending and receiving SMS messages is needed. Nearly any smartphone in combination with a 1NCE SIM can be used for this purpose. ## MO-SMS Event 1. Prepare a Mobile Originated (MO) SMS text message on a device with a 1NCE SIM. 2. The recipient number can be set to any arbitrary number (e.g., 123456) as it is ignored for routing the SMS. 3. Send the SMS message from the SIM device. 4. Once the MO-SMS was delivered, the SMS message content will be shown in the SMS Console in the 1NCE Portal My SIMs detail view and a HTTP Post SMS Event should have been delivered via the SMS Forwarder to the configured server endpoint. ## MT-SMS DLR 1. Prepare a Mobile Terminated (MT) SMS using the SMS Console in the 1NCE Portal or the 1NCE SMS API. 2. Send the MT-SMS towards an active, online 1NCE SIM device. 3. Once the SMS message was received and acknowledged by the SIM device, a Delivery Report (DLR) will be issued. 4. The DLR Event should be received by the configured SMS Forwarder Endpoint as a HTTP Patch request. *** # Simulated Post/Patch Requests To test the HTTP endpoint forwarder integration, the HTTP Post/Patch requests that would originate from the 1NCE SMS Forwarder Service can be simulated. A simulation of SMS Forwarder requests is especially useful for developing and debugging custom integrations. The simulation of the HTTP Post/Patch requests can be executed with tools like Postman or cURL using a Command Line Interface (CLI). ## MO-SMS cURL 1. Customize the cURL request shown below with the **Server Domain**, the specific **Endpoint** and optionally the **Port Number**. 2. Optionally, customize the JSON Body parameters. 3. Import the cURL command into Postman or copy the command to a CLI with cURL installed. 4. Execute the customized request to simulate a MO-SMS being delivered to the specified Endpoint by the 1NCE SMS Forwarding Service. ```curl MO-SMS HTTP Post cURL curl --location --request POST 'https://://' \ --header 'Content-Type: application/json' \ --data-raw ' { "id": 6202, "payload": "message text", "submit_date": "2018-08-17 16:31:51", "dest_address": "12345", "source_address": "1234567890123456", "dcs": 0, "endpoint": { "id": 1234567, "name": "1234567890123456" }, "organisation": { "id": 1234 }, "multi_part_info": { "partno": 1, "total": 1, "identifier": 6202 }, "pid": 0 }' ``` ## MT-SMS DLR cURL 1. Customize the cURL request shown below with the **Server Domain**, the specific **Endpoint** and optionally the **Port Number**. 2. Optionally, customize the JSON Body parameters. 3. Import the cURL command into Postman or copy the command to a CLI with cURL installed. 4. Execute the customized HTTP Patch request to simulate a Delivery Report for a MT-SMS being delivered to the specified Endpoint by the 1NCE SMS Forwarding Service. ```curl MT-SMS DLR HTTP Patch cURL curl --location --request PATCH 'https://://' \ --header 'Content-Type: application/json' \ --data-raw ' { "id": 2819195, "final_date": "2020-06-09 15:06:38", "submit_date": "2020-06-09 15:06:34", "organisation": { "id": 1234 }, "endpoint": { "name": "1234567890123456", "id": 1234567 }, "status": { "id": 4, "status": "DELIVERED" } }' ``` ### Postman Mock Server A good way to start with the 1NCE SMS Forwarder is a [Postman Mock Server](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/) A mock server can be setup fast without any need of external infrastructure. Simply create a HTPP Post and Patch endpoint with a given name. The endpoint names for both the Post and Pack need to be identical. Provide the mock server URL and the chosen Endpoint name in the 1NCE Portal SMS Forwarder configuration. Afterwards, the SMS Forwarder events should be sent to the mock server. The mock server allows to inspect real SMS events triggered by the SIMs and organization of the customer. Further, using Postman, the CURL demo events can be sent either to the mock server or the customer server implementation. --- # SMS Services Source: https://help.1nce.com/docs/blueprints-examples/examples-sms/ # Mobile Originated SMS
![](/img/blueprints-examples/examples-sms/001.png)
Mobile Originated (MO) SMS messages can be issued by devices with a 1NCE SIM card installed. As a SMS can not be send in-between different 1NCE SIM devices, all MO-SMS can only be accessed/received through the 1NCE Portal, 1NCE SMS API and the SMS Forwarder. The following sections will show examples for: * 1NCE SMS Console for MO-SMS * 1NCE API MO-SMS Integration * MO-SMS on SIM Devices Examples for the 1NCE SMS Forwarding Service can be found in the SMS Forwarder section. *** # Mobile Terminated SMS
![](/img/blueprints-examples/examples-sms/002.png)
Mobile Terminated (MT) SMS messages are destined for a device with an installed 1NCE SIM. Such MT-SMS can be issued via the 1NCE Portal using the SMS Console or using the 1NCE API. While the SMS console is great for debugging and getting started, the usage through the 1NCE API provides a fully-featured access to automate the SMS messing sending process. The following subsections will show examples for: * 1NCE SMS Console for MT-SMS * 1NCE API MT-SMS Integration * MT-SMS on SIM Devices --- # Mobile Originated SMS Source: https://help.1nce.com/docs/blueprints-examples/examples-sms/examples-mo-sms/ ## 1NCE Portal / SMS Console This section covers how to use the SMS Console inside the 1NCE Portal to view the MO-SMS messages of a specific 1NCE SIM. Please note that the data retention of seven days applies to the SMS Console, SMS older than seven days will no longer be displayed. ### Viewing MO-SMS 1. Login to the 1NCE Portal and go the the **My SIMs** tab. 2. Select the **SIM** for which the MO-SMS should be viewed from the list of all SIM cards. 3. Navigate to the **SMS Tab** at the bottom of the SIM details page to access the SMS Console.
![SMS_Console_MO.png](/img/blueprints-examples/examples-sms/examples-mo-sms/a9af544-SMS_Console_MO.png)
4. The list view will show both MT-SMS and MO-SMS messages. For both types, the **Status**, **Submitted**, **Finalized**, **Source Address** and **Payload** are shown. 5. A MO-SMS will remain in the pending status without being finalized until it was received and acknowledged by an SMS Forwarder Endpoint. As this integration is optional, by default the MO-SMS will stay in the pending state. *** ## 1NCE SMS API The 1NCE API offers another solution to access Mobile Originated SMS messages. For a specific SIM card a list of MT/MO-SMS or single SMS messages based on the SMS ID can be queried. A good starting point is the API Explorer to get familiar with the API calls. From the API Explorer, ready to use code snippets and cURL queries can be obtained to integrate into custom applications. ### API Prerequisites Before using the SMS API requests, an authentication token needs to be requested using the `/oauth/token` API request. For using the MT-SMS functionality, an ICCID of a 1NCE SIM is needed to send, monitor and manage the SMS messages for this SIM. ### Retrieving MO-SMS With the 1NCE SMS API, the received MO-SMS can be retrieved with some simple HTTP queries. Open the dropdowns below to see example guides for integration.
Get MT/MO-SMS List With the 1NCE API a list of MT/MO-SMS can be queried to get detailed information about the SMS message delivery status as well as have access to the payloads. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which a list of messages should be queried. 3. As a list of MT/MO-SMS messages will be returned, the **Page Size** parameter specifies how many list entries per loaded page will be returned. 4. As it is possible to have multiple pages, the **Page** parameter specifies the to be queried page. If there is more than one page present, the response header will include the total item count and the total page count. 5. The optional **Sort** parameter allows to sort the queried list to be sorted by the Status and IP Address keys. 6. Execute the **HTTP Get** request to query the MT/MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MO-SMS is shown. Please note that this query also shows any MT-SMS messages from the specified SIM. ```curl Query MO-SMS cURL Example curl --request GET \ --url 'https://api.1nce.com/management-api/v1/sims//sms?page=1&pageSize=10&sort=status%2Cip_address' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MO-SMS Response Example [ { "id": 7478676, "submit_date": "2021-12-01T12:13:52.000+0000", "delivery_date": "2021-12-01T12:13:52.000+0000", "expiry_date": "2021-12-02T12:13:52.000+0000", "retry_date": "2021-12-01T12:44:09.000+0000", "last_delivery_attempt": "2021-12-01T12:28:09.000+0000", "retry_count": "3", "source_address": "", "iccid": "", "msisdn": "", "imsi": "", "udh": "", "payload": "Another MO-SMS!", "status": { "id": 3, "description": "BUFFERED" }, "sms_type": { "id": 2, "description": "MO" }, "source_address_type": { "id": 145, "description": "International" } } ] ```
Get Individual MO-SMS Besides a list of MT/MO-SMS the 1NCE API allows to query specific SMS messages based on ICCD and SMS ID. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which the specific MO-SMS should be queried. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS. 4. Execute the **HTTP Get** request to query the specific MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MO-SMS is shown. ```curl Query MO-SMS cURL Example curl --request GET \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MO-SMS Response Example { "id": 7478676, "submit_date": "2021-12-01T12:13:52.000+0000", "delivery_date": "2021-12-01T12:13:52.000+0000", "expiry_date": "2021-12-02T12:13:52.000+0000", "retry_date": "2021-12-01T12:44:09.000+0000", "last_delivery_attempt": "2021-12-01T12:28:09.000+0000", "retry_count": "3", "source_address": "", "iccid": "", "msisdn": "", "imsi": "", "udh": "", "payload": "Another MO-SMS!", "status": { "id": 3, "description": "BUFFERED" }, "sms_type": { "id": 2, "description": "MO" }, "source_address_type": { "id": 145, "description": "International" } } ```
*** ## SIM Device MO-SMS MO-SMS messages are issued from devices which use a 1NCE SIM for connectivity. The SMS service is available without the need to establish a PDP Data Session. Please note that SMS is not possible with NB-IoT. ### MO-SMS with Smartphone For testing and trying out the SMS Service, 1NCE recommends to use a simple smartphone with a 1NCE SIM to send MO-SMS. 1. Insert the **1NCE SIM** into the smartphone used for testing. 2. Enable **Roaming**on the device, as the 1NCE SIM appears always as roaming. Ensure that a network connection is available through the network status indicator of the phone. 3. Open up the **SMS Messaging App** of the used smartphone. 4. The target **Phone Number** can be set to any arbitrary number as the 1NCE network ignores this parameter and forwards all MO-SMS to the Portal/API/SMS Forwarder. External phone numbers are not reachable. 5. Prepare a basic **SMS Message** and send the MO-SMS message. 6. Check in the 1NCE Portal, through the API or if implemented the SMS Forwarder to see the received MO-SMS. ### MO-SMS with IoT Devices Most IoT modem devices allow to send MO-SMS via AT Commands. Please check with the manufacturer documentation how to send MO-SMS or check the 1NCE Hardware & Modem Guides. --- # Mobile Terminated SMS Source: https://help.1nce.com/docs/blueprints-examples/examples-sms/examples-mt-sms/ ## 1NCE Portal / SMS Console This section covers the usage of the 1NCE Portal and the SMS Console to send MT-SMS to one individual 1NCE SIMs. The SMS Console only supports 7-Bit GSM Alphabet Text MT-SMS. For using more advanced features, please refer to the 1NCE API examples. ### Alphabet Text SMS Messages 1. Login to the 1NCE Portal and go the the **My SIMs** tab. 2. Select the **SIM** to which the MT-SMS messages should be issued from the list of all SIM cards. 3. Navigate to the **SMS Tab** at the bottom of the SIM details page to access the SMS Console.
![SMS_Console_01.png](/img/blueprints-examples/examples-sms/examples-mt-sms/c31f7b3-SMS_Console_01.png)
4. Enter a **Source Address**. This address is not needed for routing the SMS, but some devices might require a certain originating address/phone number to validate the sender. 5. Add a **7-Bit GSM Alphabet Text Payload** which should have a maximum length of **160 Characters**. Using the SMS Console only text messages with Data Coding Scheme (DCS) 0 and no Concatenated SMS are possible. Please refer to the 1NCE SMS API examples for more advanced features. 6. Click the **Send** button to issue the MT-SMS towards the 1NCE SIM device.
![SMS_Console_02.png](/img/blueprints-examples/examples-sms/examples-mt-sms/e08b43b-SMS_Console_02.png)
7. After sending the MT-SMS, please wait a bit as the message is being processed. The list view of the SMS messages can be manually updated. 8. While the MT-SMS is in transit and has not been acknowledged by the receiving device, the status is shown as **Pending**. 9. If the receiving device is attached to the network (not NB-IoT), the MT-SMS will be received, the status changes to **Delivered** and the **Finalized** timestamp will be shown. 10. If the receiving device is currently not attached, the MT-SMS will stay in the **Pending** state for up to 24 hours. The 1NCE network tries to redeliver this MT-SMS as soon as the devices becomes attached. After 24 hours, the MT-SMS will go the the **Failed** state and the SMS message will not be redelivered. *** ## 1NCE SMS API This section covers all topics around sending, monitoring and managing MT-SMS messages with the the 1NCE API. A good starting point is the API Explorer to get familiar with the API calls. From the API Explorer, ready to use code snippets and cURL queries can be obtained to integrate into custom applications. ### API Prerequisites Before using the SMS API requests, an authentication token needs to be requested using the `/oauth/token` API request. For using the MT-SMS functionality, an ICCID of a 1NCE SIM is needed to send, monitor and manage the SMS messages for this SIM. ### Sending MT-SMS The examples listed below show common use cases for sending MT-SMS with the 1NCE API. Please open the dropdowns to get a full guide on how to send these types of SMS messages.
7-Bit Alphabet Text SMS Messages This example show a simple MT-SMS message with a maximum 160 character 7-bit GSM Alphabet SMS message payload. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the 7-bit GSM Alphabet Text SMS Message. Please note the maximum length of the SMS is 160 characters. 5. For sending 7-bit GSM Alphabet SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 0. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a simple 7-bit GSM Alphabet MT-SMS message. ```curl 7-Bit Alphabetic MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "This is a MT-SMS message.", "dcs": 0, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
UCS-2 SMS Messages The Universal Coded Character Set (UCS-2) defines two bytes per encoded character. The example shown is similar to a normal 7-Bit GSM Alphabet MT-SMS with the needed DCS adaption and a shorter payload of 70 characters. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the UCS-2 MT-SMS Message. Please note the maximum length of the UCS-2 SMS is only 70 characters. 5. For sending UCS-2 SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 8. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a UCS-2 MT-SMS message. ```curl UCS-2 MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "UCS-2 MT-SMS message.", "dcs": 8, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
Binary SMS Messages Binary encoded MT-SMS messages are often used to send machine readable commands to a device in a compressed message. The payload of binary SMS messages need to be a HEX String and the Data Coding Scheme needs to be set to 4. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the Binary MT-SMS Message as HEX String. Please note the maximum length of the payload is 140 bytes. 5. For sending Binary SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 4. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a Binary MT-SMS message. ```curl Binary MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "54657374534d53", "dcs": 4, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
Concatenated SMS Messages All types of MT-SMS messages (7-Bit GSM Alphabet, Binary, UCS-2) can be send as a chain of concatenated SMS. The User Data Header (DH) is needed to inform the receiving device of the concatenated SMS. Please note that the usage of the UDH decreases the payload size by 6 bytes to 134 bytes (153 7-Bit characters). 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the MT-SMS Message. Please ensure that the maximum length matches the used payload type set in the DCS. 5. Specify the **Data Coding Scheme (DCS)** according to the desired payload time. 6. The **User Data Header (UDH)** is a 6 byte value encoded as HEX String. The first 4 bytes contain the UDH length, Information Element Identifier, header length without the first two fields, CSMS reference ID, total SMS Parts and current Part Number. The last two fields need to be altered based on the total amount of concatenated SMS messages and the current SMS Part Number. The table below shows an example UDH for a 3 part Concatenated SMS. | UHD Field | Example | | :----------------------------- | :------ | | UDH Length | 0x05 | | Information Element Identifier | 0x00 | | UDH Header Length - 2 Byte | 0x03 | | CSMS Reference ID | 0xCC | | SMS Part Count | 0x03 | | Current SMS Part (1/3) | 0x01 | 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below in the separate tabs are three the cURL example for a a three part concatenated MT-SMS. ```curl Concatenated MT-SMS Part 01 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 01", "dcs": 0, "udh": "050003CC0301", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ``` ```curl Concatenated MT-SMS Part 02 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 02", "dcs": 0, "udh": "050003CC0302", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ``` ```curl Concatenated MT-SMS Part 03 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 03", "dcs": 0, "udh": "050003CC0303", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
### Monitoring MT-SMS Besides sending different types MT-SMS, the API can also be used to monitor and obtain a list of issued MT-SMS messages. Expand the dropdowns below to see the possibilities of querying the MT-SMS API.
Get MT/MO-SMS List With the 1NCE API a list of MT/MO-SMS can be queried to get detailed information about the SMS message delivery status as well as have access to the payloads. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which a list of messages should be queried. 3. As a list of MT/MO-SMS messages will be returned, the **Page Size** parameter specifies how many list entries per loaded page will be returned. 4. As it is possible to have multiple pages, the **Page** parameter specifies the to be queried page. If there is more than one page present, the response header will include the total item count and the total page count. 5. The optional **Sort** parameter allows to sort the queried list to be sorted by the Status and IP Address keys. 6. Execute the **HTTP Get** request to query the MT/MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MT-SMS in the second tab is shown. Please note that this query also shows any MO-SMS messages from the specified SIM. ```curl Query MT-SMS cURL Example curl --request GET \ --url 'https://api.1nce.com/management-api/v1/sims//sms?page=1&pageSize=10&sort=status%2Cip_address' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MT-SMS Response Example [ { "id": 7476638, "submit_date": "2021-12-01T07:43:34.000+0000", "delivery_date": "2021-12-01T07:43:34.000+0000", "expiry_date": "2021-12-02T07:43:34.000+0000", "final_date": "2021-12-01T07:43:35.000+0000", "last_delivery_attempt": "2021-12-01T07:43:35.000+0000", "retry_count": "0", "source_address": "1234567", "iccid": "", "msisdn": "", "imsi": "", "msc": "", "udh": "", "payload": "This is a 1NCE MT-SMS Test!", "status": { "id": 4, "description": "DELIVERED" }, "sms_type": { "id": 1, "description": "MT" }, "source_address_type": { "id": 161, "description": "National" } } ] ```
Get Individual MT-SMS Besides a list of MT/MO-SMS the 1NCE API allows to query specific SMS messages based on ICCD and SMS ID. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which the specific MT-SMS should be queried. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS or from the Location Response Header of the Send MT-SMS HTTP Post request. 4. Execute the **HTTP Get** request to query the specific MT-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MT-SMS in the second tab is shown. ```curl Query MT-SMS cURL Example curl --request GET \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MT-SMS Response Example { "id": 7476638, "submit_date": "2021-12-01T07:43:34.000+0000", "delivery_date": "2021-12-01T07:43:34.000+0000", "expiry_date": "2021-12-02T07:43:34.000+0000", "final_date": "2021-12-01T07:43:35.000+0000", "last_delivery_attempt": "2021-12-01T07:43:35.000+0000", "retry_count": "0", "source_address": "1234567", "iccid": "", "msisdn": "", "imsi": "", "msc": "", "udh": "", "payload": "This is a 1NCE MT-SMS Test!", "status": { "id": 4, "description": "DELIVERED" }, "sms_type": { "id": 1, "description": "MT" }, "source_address_type": { "id": 161, "description": "National" } } ```
### Manage MT-SMS Through the API, issued MT-SMS that have not been delivered yet can be deleted from the SMS queue. The dropdown below show how to use the SMS API to manage MT-SMS.
Delete MT-SMS A MT-SMS that has not been delivered and is currently in the retry loop, can be delete using the 1NCE SMS API. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM for which a MT-SMS should be deleted. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS or from the Location Response Header of the Send MT-SMS HTTP Post request. 4. Execute the **HTTP Delete** to delete the buffered MT-SMS. In the code example below, a sample HTTP Delete cURL request to delete a buffered MT-SMS is shown. ```curl Delete MT-SMS cURL Example curl --request DELETE \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ```
*** ## SIM Device MT-SMS MT-SMS messages are issued towards devices which use a 1NCE SIM for connectivity. The SMS service is available without the need to establish a PDP Data Session. Please note that SMS is not possible with NB-IoT. ### MT-SMS with Smartphone For testing and trying out the SMS Service, 1NCE recommends to use a simple smartphone with a 1NCE SIM to receive MT-SMS. 1. Insert the **1NCE SIM** into the smartphone used for testing. 2. Enable **Roaming** on the device, as the 1NCE SIM appears always as roaming. Ensure that a network connection is available through the network status indicator of the phone. 3. Open up the **SMS Messaging App** of the used smartphone. 4. Prepare a **SMS Message** using one of the above mentioned methods (1NCE Portal or 1NCE API) to issue a MT-SMS. 5. Send the message towards the specific **ICCID SIM** which is inserted in the smartphone. 6. Check the smartphone for an incoming SMS message. ### MT-SMS with IoT Devices Most IoT modem devices can receive and save MT-SMS. The control of the SMS management on the modem side is handled via AT Commands. Please check with the manufacturer documentation how to receive and query MT-SMS or check the 1NCE Hardware & Modem Guides. --- # VPN Service Source: https://help.1nce.com/docs/blueprints-examples/examples-vpn/ Each 1NCE SIM has a private IP and is connected via the Internet Breakout using Network Address Translation to the open internet. By default the connection establishment is unidirectional from the SIM device to a server/service in the internet. The 1NCE VPN Service enables 1NCE customers to connect and transmit data bidirectional with their SIM devices via a Virtual Private Network (VPN) connection. This section covers the setup of the 1NCE VPN client for Windows, Linux and Mac OS to establish a connection with the 1NCE Network Service. For custom OpenVPN installs, advanced routing or specific application setups refer to the OpenVPN Documentation. *** # Setup Guides For a detailed guide on how to install the VPN Client click on one of the following Operating Systems:
![](/img/blueprints-examples/examples-vpn/13f2388-windows.svg)
--- # VPN Setup Linux Source: https://help.1nce.com/docs/blueprints-examples/examples-vpn/examples-vpn-linux/
![](/img/blueprints-examples/examples-vpn/examples-vpn-linux/001.png)
Linux is very popular as a server operating system, thus it is used in many production systems for running applications. The 1NCE VPN service can be used with the OpenVPN client for Linux. This section covers the general installation and operation procedure of OpenVPN using the 1NCE VPN Service. Please note that due to the many flavors of the Linux operating system, the install procedure might be different for other Linux flavors. In the example, Ubuntu is used as operating system and the install process is carried out via Command Line Interface (CLI). Please keep the `xx-region-x-client.conf` and the `credentials.txt` file downloaded from the 1NCE Portal at hand to get started. A current version of the OpenVPN client for Windows needs to be installed. For this please download the latest version from the OpenVPN Download Portal. *** # Linux Routing & Interface Each 1NCE SIM has a fixed IP from the private IP space (RFC 1597) allocated. The connected VPN client also has a static address from the private IP space assigned. Please note that these addresses might not necessarily be from the same subnet, which has no impact on the functionality. > 📘 Pushed Routes and Updates > > The routing for all assigned SIM IP Subnets is pushed during the initialization of the connection. If new IP spaces are assigned as a result of a larger SIM order, please restart the VPN connection to obtain the latest routes. The customer specific traffic routing from the VPN terminating client to the specific applications/servers interfaces needs to be set up on configured by the customer and is specific to the application case. An example of IP routes pushed from the VPN server to the client are listed below. Please note that the IP addresses in the following examples are just illustrative and may not be the same as in your configuration. A short snippet from the OpenVPN log file obtained during the start of a VPN connection. It shows the routes being pushed towards the Linux VPN interface. ```text Fri Jan 28 08:42:19 2022 /sbin/ip link set dev tun0 up mtu 1500 Fri Jan 28 08:42:19 2022 /sbin/ip addr add dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/32 via x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/24 via x.x.x.x ``` Tunnel Adapter of the OpenVPN connection in Linux shows the VPN client IP address. This address should be used to connect with a SIM card to the VPN client/customer server. ```text tun0: flags=4305 mtu 1500 inet 10.66.x.x netmask 255.255.255.255 destination 10.66.x.x inet6 fe80::dde8:427c:xxxx:xxxx prefixlen 64 scopeid 0x20 unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 100 (UNSPEC) RX packets 0 bytes 0 (0.0 B) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 1 bytes 48 (48.0 B) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 ``` Output of `route` in Linux CLI shows the current routes configured on the system. OpenVPN pushed the routes towards the SIMs after a VPN connection has been established. Please ensure that there are not local IP address conflicts within the network and SIM IP ranges. ```text Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 10.64.x.x 10.66.x.x 255.255.255.255 UGH 0 0 0 tun0 10.66.x.x 0.0.0.0 255.255.255.255 UH 0 0 0 tun0 10.210.x.x 10.66x.x 255.255.255.0 UG 0 0 0 tun0 ``` Connecting the VPN client on Linux machine creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. *** # Linux VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. To install and operate the Linux OpenVPN client, the example uses the Command Line Interface (CLI) to configure the 1NCE VPN Service. Please keep the configuration and credentials file from the 1NCE Portal at hand. 1. Ensure that the operating system is up-to-date and the latest package sources are available. ```text Ubuntu Update sudo apt update sudo apt upgrade ``` 2. Install OpenVPN using the system packet manager. Optionally a custom OpenVPN version can be build from source code if needed. ```text Open VPN Install sudo apt install openvpn ``` 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Linux/MacOS** as configuration medium and download the OpenVPN *xx-region-x-client.conf* and *credentials.txt* files.
![1nce-vpn-linux.png](/img/blueprints-examples/examples-vpn/examples-vpn-linux/d5055b7-1nce-vpn-linux.png)
4. Place the *xx-region-x-client.conf* and *credentials.txt* in the OpenVPN configuration folder, typically */etc/openvpn/*. 5. Optionally rename the *xx-region-x-client.conf* and *credentials.txt* files to make their names unique and more transparent. 6. If required, change the path of the *credentials.txt* file in the *xx-region-x-client.conf* on line *auth-user-pass*. This is needed if the credentials file is placed somewhere else besides the default location or if the files were renamed. 7. Make any alterations to the VPN configuration (e.g. add logging or custom parameters) before starting the client the first time. 8. As a first run, start the VPN client directly in the CLI and not as a service. This will provide a direct output of the logs and makes debugging easier. Adapt the path to the configuration file to the location and filename of the used config files. ```text OpenVPN Start sudo openvpn --config /etc/openvpn/1nce-conf.conf ``` ```text OpenVPN Connection Log Fri Jan 28 08:42:12 2022 OpenVPN 2.4.7 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [LZ4] [EPOLL] [PKCS11] [MH/PKTINFO] [AEAD] built on Jul 19 2021 Fri Jan 28 08:42:12 2022 library versions: OpenSSL 1.1.1f 31 Mar 2020, LZO 2.10 Fri Jan 28 08:42:12 2022 TCP/UDP: Preserving recently used remote address: [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 Socket Buffers: R=[212992->212992] S=[212992->212992] Fri Jan 28 08:42:12 2022 UDP link local: (not bound) Fri Jan 28 08:42:12 2022 UDP link remote: [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 NOTE: UID/GID downgrade will be delayed because of --client, --pull, or --up-delay Fri Jan 28 08:42:12 2022 TLS: Initial packet from [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 VERIFY OK: depth=1, C=de, ST=North Rhine-Westphalia, L=Cologne, O=1nce, OU=1nce Operations, CN=x, name=1nce Fri Jan 28 08:42:12 2022 VERIFY KU OK Fri Jan 28 08:42:12 2022 Validating certificate extended key usage Fri Jan 28 08:42:12 2022 ++ Certificate has EKU (str) TLS Web Server Authentication, expects TLS Web Server Authentication Fri Jan 28 08:42:12 2022 VERIFY EKU OK Fri Jan 28 08:42:12 2022 VERIFY OK: depth=0, C=de, ST=North Rhine-Westphalia, L=Cologne, O=1nce, OU=1nce Operations, CN=x, name=1nce Fri Jan 28 08:42:13 2022 Control Channel: TLSv1.3, cipher TLSv1.3 TLS_AES_256_GCM_SHA384, 2048 bit RSA Fri Jan 28 08:42:13 2022 [x] Peer Connection Initiated with [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:14 2022 SENT CONTROL [x]: 'PUSH_REQUEST' (status=1) Fri Jan 28 08:42:19 2022 SENT CONTROL [x]: 'PUSH_REQUEST' (status=1) Fri Jan 28 08:42:19 2022 PUSH: Received control message: 'PUSH_REPLY,route x.x.x.x,topology net30,ping 5,ping-restart 30,route x.x.x.x x.x.x.x,ifconfig x.x.x.x x.x.x.x,peer-id 322,cipher AES-256-GCM' Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: timers and/or timeouts modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: --ifconfig/up options modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: route options modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: peer-id set Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: adjusting link_mtu to 1624 Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: data channel crypto options modified Fri Jan 28 08:42:19 2022 Data Channel: using negotiated cipher 'AES-256-GCM' Fri Jan 28 08:42:19 2022 Outgoing Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key Fri Jan 28 08:42:19 2022 Incoming Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key Fri Jan 28 08:42:19 2022 ROUTE_GATEWAY x.x.x.x/x.x.x.x IFACE=ens3 Fri Jan 28 08:42:19 2022 TUN/TAP device tun0 opened Fri Jan 28 08:42:19 2022 TUN/TAP TX queue length set to 100 Fri Jan 28 08:42:19 2022 /sbin/ip link set dev tun0 up mtu 1500 Fri Jan 28 08:42:19 2022 /sbin/ip addr add dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/32 via x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/24 via x.x.x.x Fri Jan 28 08:42:19 2022 GID set to nogroup Fri Jan 28 08:42:19 2022 UID set to root Fri Jan 28 08:42:19 2022 Initialization Sequence Completed ^C Fri Jan 28 08:42:21 2022 event_wait : Interrupted system call (code=4) Fri Jan 28 08:42:21 2022 SIGTERM received, sending exit notification to peer Fri Jan 28 08:42:24 2022 /sbin/ip route del x.x.x.x/32 Fri Jan 28 08:42:24 2022 /sbin/ip route del x.x.x.x/24 Fri Jan 28 08:42:24 2022 Closing TUN/TAP interface Fri Jan 28 08:42:24 2022 /sbin/ip addr del dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:24 2022 SIGTERM[soft,exit-with-notification] received, process exiting ``` 9. OpenVPN will start and try to connect to the VPN server. The logs (see second tab) will be printed to the CLI and show the current connection status. If there are any unexpected errors, check the configuration and setup and please try again. 10. The connection can be closed by CTRL+C. 11. To run the 1NCE VPN with OpenVPN client as a system service in the background, use the `sytemctl` commands. Ensure that the config name provided to start the VPN client matches the filename in `/etc/openvpn/`. Note that the `.conf` extension needs to be omitted. ```text sudo systemctl start openvpn@1nce-conf sudo systemctl status openvpn@1nce-conf sudo systemctl restart openvpn@1nce-conf sudo systemctl stop openvpn@1nce-conf ``` 12. Once the service is up and running, the status can be queried to see the current VPN connection status. 13. To restart or stop the VPN client, use the `restart` or `stop` command. If a successful connection is established, the Linux system should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. *** # Monitoring and Logging The 1NCE VPN Service on Linux with OpenVPN allows for easy monitoring and optional logging. This is especially useful for debugging the VPN setup in case of connectivity issues. By default, the VPN connection towards the 1NCE Network is updated once per hour. This renewal process should be logged in the monitoring. If this renewal happens very frequently, it might point towards an unstable connection or two VPN clients fighting for the same single connection. ## Extended Logging For extended logging over longer periods of time or with a defined information granularity, the *xx-region-x-client.conf* configuration needs to be adapted. The example below shows possible configuration parameters.\ The Verbosity *verb\* defines the amount of detail included in the log file. The default value of 3 offers a good mix between detail and abstraction. The settable range is 1 to 4. Please note that setting the log level to 4 will generate larger log files.\ The path where a log file will be saved is specified by *log\/openvpn.log*. Please adapt the path to a valid place in Linux to store the logs.\ Log files can be automatically rotated. The example shown below provides a basic starting point for weekly log file rotation. For more information please see OpenVPN Documentation. ```text verb log /openvpn.log /openvpn.log { weekly rotate 12 copytruncate compress delaycompress missingok notifempty } ``` --- # VPN Setup Mac OS Source: https://help.1nce.com/docs/blueprints-examples/examples-vpn/examples-vpn-macos/
![](/img/blueprints-examples/examples-vpn/examples-vpn-macos/001.png)
For using the 1NCE VPN Service with Mac OS, it is recommended to use the Tunnelblick application. If offers an easy to configure and use interface for OpenVPN client connectivity. Please refer to Tunnelblick for more details about the Mac OS OpenVPN client. *** # Mac OS VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. 1. Download the current version of the **Tunnelblick** client for Mac OS. (Tunnelblick Download 2. Install the the OpenVPN client for Mac OS. Follow the default install instructions. 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Mac OS** as configuration medium and download the OpenVPN *xx-region-x-client.conf* and *credentials.txt* files.
![1nce-vpn-linux.png](/img/blueprints-examples/examples-vpn/examples-vpn-macos/35112bd-1nce-vpn-linux.png)
4. Import the *xx-region-x-client.conf* and *credentials.txt* into Tunnelblick application. Refer to Tunnelblick Install Guide for details about the setup. 5. Once the configuration is installed. The connection can be established by clicking on *Connect* inside the application. 6. A new pop-up will be shown for the client connecting. It shows the logs of the current connection attempt. After a few seconds the client should connect and the pop-up should be closed automatically. The VPN connection can be terminated by clicking **Disconnect** in the OpenVPN task bar menu. If a successful connection is established, the computer should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. --- # VPN Setup Windows Source: https://help.1nce.com/docs/blueprints-examples/examples-vpn/examples-vpn-windows/
![](/img/blueprints-examples/examples-vpn/examples-vpn-windows/001.png)
The Windows platform is often used for testing on personal computers or in a Windows Server environment. This section covers the basic setup the 1NCE VPN Service on a Windows PC. Further the data routing needed for communicating between the VPN client and the 1NCE SIMs is shown. References to examples for testing and debugging the Windows VPN integrations are provided. Please keep the `xx-region-x-client.ovpn` and the `credentials.txt` file downloaded from the 1NCE Portal at hand to get started. A current version of the OpenVPN client for Windows needs to be installed. For this please download the latest version from the OpenVPN Download Portal. *** # Windows Routing & Interface Each 1NCE SIM has a fixed IP from the private IP space (RFC 1597) allocated. The connected VPN client also has a static address from the private IP space assigned. Please note that these addresses might not necessarily be from the same subnet, which has no impact on the functionality. > 📘 Pushed Routes and Updates > > The routing for all assigned SIM IP Subnets is pushed during the initialization of the connection. If new IP spaces are assigned as a result of a larger SIM order, please restart the VPN connection to obtain the latest routes. The customer specific traffic routing from the VPN terminating client to the specific applications/servers interfaces needs to be set up on configured by the customer and is specific to the application case. An example of IP routes pushed from the VPN server to the client are listed below. Please note that the IP addresses in the following examples are just illustrative and may not be the same as in your configuration. A short snippet from the OpenVPN log file obtained during the start of a VPN connection using a Windows PC. It shows the routes being pushed towards the Windows system. ```text Notified TAP-Windows driver to set a DHCP IP/netmask of 10.64.80.2/255.255.255.252 on interface {ACF7A788-1EF1-43D2-9CE4-240945672EF6} [DHCP-serv: 10.64.80.2, lease-time: 31536000] Successful ARP Flush on interface [14] {ACF7A788-1EF1-43D2-9CE4-240945672EF6} MANAGEMENT: >STATE:1621401048,ASSIGN_IP,,10.64.80.2,,,, ROUTES: 2/2 succeeded len=2 ret=1 a=0 u/d=up MANAGEMENT: >STATE:1621401053,ADD_ROUTES,,,,,, C:\WINDOWS\system32\route.exe ADD 10.64.0.1 MASK 255.255.255.255 10.64.80.2 Route addition via service succeeded C:\WINDOWS\system32\route.exe ADD 10.119.x.x MASK 255.255.252.0 10.64.80.2 ``` Tunnel Adapter of the OpenVPN connection in Windows shows the VPN client IP address. This address should be used to connect with a SIM card to the VPN client/customer server. ```text Connection-specific DNS suffix: Link-local IPv6 Address . : fe80::xxxx:xxxx:xxxx:xxxx IPv4 Address . . . . . . . . . . : 10.64.80.2 Subnet Mask . . . . . . . . . . : 255.255.255.252 Default Gateway . . . . . . . . . : ``` Output of `route print` in Windows Command Line shows the current routes configured on the system. OpenVPN pushed the routes towards the SIMs after a VPN connection has been established. Please ensure that there are not local IP address conflicts within the network and SIM IP ranges. ```text IPv4 Routen Table =========================================================================== Active Routes: Network Destination Netmask Gateway Interface Metric 10.64.0.1 255.255.255.255 10.64.80.3 10.64.80.1 4506 10.64.80.1 255.255.255.252 On-Link 10.64.80.1 4506 10.64.80.2 255.255.255.255 On-Link 10.64.80.1 4506 10.64.80.4 255.255.255.255 On-Link 10.64.80.1 4506 10.119.x.x 255.255.252.0 10.64.80.3 10.64.80.1 4506 224.0.0.0 240.0.0.0 On-Link 10.64.80.1 4506 255.255.255.255 255.255.255.255 On-Link 10.64.80.1 4506 ``` Connecting the VPN client on PC or server creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. *** # Windows VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. The Windows platform is often used for testing on personal computers or in a Windows Server environment. In this section, the configuration of the 1NCE VPN Service for the Windows Operating System is shown. 1. Download the current version of the **OpenVPN** client for Windows. (OpenVPN Download 2. Install the the OpenVPN client for Windows. Follow the default install instructions. 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Windows** as configuration medium and download the OpenVPN *xx-region-x-client.ovpn* and *credentials.txt* files.
![VPN_Windows_Configuration_01.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/d5ac052-VPN_Windows_Configuration_01.png)
4. Place the *xx-region-x-client.ovpn* and *credentials.txt* in the OpenVPN configuration folder, typically *C:\\Program Files\\OpenVPN\\config*. 5. If required, change the path of the *credentials.txt* file in the *xx-region-x-client.ovpn* on line *auth-user-pass*. This is needed if the credentials file is placed somewhere else besides the default location. 6. Optionally, rename the *xx-region-x-client.ovpn* file to make it unique in the OpenVPN user interface. 7. Start the **OpenVPN GUI** program. Typically it will open in the task bar. 8. Right click the **OpenVPN Icon** in the task bar menu. 9. If more than one client is configured, a list of VPN connections is shown. 10. Select the desired *client*, renamed configuration or if only one client is configured click on **Connect**.
![VPN_Windows_Configuration_02.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/6b2e31c-VPN_Windows_Configuration_02.png)
11. A new pop-up will be shown for the client connecting. It shows the logs of the current connection attempt. After a few seconds the client should connect and the pop-up should be closed automatically.
![VPN_Windows_Configuration_03.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/e950072-VPN_Windows_Configuration_03.png)
The VPN connection can be terminated by clicking **Disconnect** in the OpenVPN task bar menu. If a successful connection is established, the computer should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. *** # Monitoring and Logging The 1NCE VPN Service on Windows with OpenVPN allows for easy monitoring and optional logging. This is especially useful for debugging the VPN setup in case of connectivity issues. By default, the VPN connection towards the 1NCE Network is updated once per hour. This renewal process should be logged in the monitoring. If this renewal happens very frequently, it might point towards an unstable connection or two VPN clients fighting for the same single connection. ## Current Session Logs Right click on the task tray icon and select **View Log**. This will bring up the log of the currently established connection. In the logs, details about the connection setup, reconnect, keep-alive and pushed routes can be found. Please always include these logs in any VPN related Support Ticket. ## Extended Logging For extended logging over longer periods of time or with a defined information granularity, the *xx-region-x-client.ovpn* configuration needs to be adapted. The example below shows possible configuration parameters.\ The Verbosity *verb\* defines the amount of detail included in the log file. The default value of 3 offers a good mix between detail and abstraction. The settable range is 1 to 4. Please note that setting the log level to 4 will generate larger log files.\ The path where a log file will be saved is specified by *log\/openvpn.log*. Please adapt the path to a valid place in Windows to store the logs.\ Log files can be automatically rotated. The example shown below provides a basic starting point for weekly log file rotation. For more information please see OpenVPN Documentation. ```text verb log /openvpn.log /openvpn.log { weekly rotate 12 copytruncate compress delaycompress missingok notifempty } ``` --- # Quectel BG95-M3 Source: https://help.1nce.com/docs/blueprints-examples/quectel-bg95-m3/ AT command guide for: Quectel BG95, BG77, and BG600L series The BG95-M3 Mini PCIe is a wireless communication module that supports multiple cellular network technologies including LTE Cat M1, Cat NB2, and EGPRS. These technologies are designed to provide low-power, low-bandwidth, and low-cost connectivity for IoT (Internet of Things) devices. # Network Registration Network registration is the process by which a cellular device connects to a cellular network and obtains the necessary credentials to access the network's services. This process involves several steps, including network selection, authentication, and registration. - 🦉 [BG95-M3 Network Registration](/docs/blueprints-examples/bg95-m3-network-registration) # ICMP Ping - 🦉 [BG95-M3 ICMP Ping](/docs/blueprints-examples/bg95-m3-icmp-ping) # TCP Client - 🦉 [BG95&BG77 TCP Client Connection](/docs/blueprints-examples/bg95bg77-tcp-client-connection) # 1NCE OS UDP Protocol - 🦉 [BG95-M3 1NCE OS UDP](/docs/blueprints-examples/bg95-m3-1nce-os-udp) --- # Quectel EC25 & EC21 Source: https://help.1nce.com/docs/blueprints-examples/quectel-ec25-ec21/ EC25 & EC21 AT command interface defaults to the GSM character set. EC25 & EC21 modules support the following character sets: - GSM format - UCS2 - IRA # EC25 RAT Configuration Setup and configure the Quectel EC25 or EC21 for use with 1NCE SIM. - 📲 [EC25 RAT Configuration](/docs/blueprints-examples/ec25-rat-configuration) # Network Registration: Network registration is the process by which a cellular device connects to a cellular network and obtains the necessary credentials to access the network's services. This process involves several steps, including network selection, authentication, and registration. - 📲 [EC25 Network Registration](/docs/blueprints-examples/ec25-network-registration) # ICMP Ping Connect with the EC25 or EC21 to a mobile network, start a data session, and issue an ICMP Ping request. - 📲 [EC25 ICMP Ping](/docs/blueprints-examples/ec25-icmp-ping) # MO-SMS Send an SMS message from an EC25 or EC21 to the 1NCE SMS Forwarding Service. - 📲 [EC25 MO-SMS](/docs/blueprints-examples/ec25-mo-sms) # MT-SMS Receive SMS messages with a Quectel EC25 or EC21. - 📲 [EC25 MT-SMS](/docs/blueprints-examples/ec25-mt-sms) # TCP Client Connect to a TCP Server and send/receive data using a Quectel EC25 or EC21. - 📲 [EC25 TCP Client Connection](/docs/blueprints-examples/ec25-tcp-client-connection) # 1NCE OS UDP Protocol - 🦉 [EC25 & EC21 1NCE OS UDP](/docs/blueprints-examples/ec25-ec21-1nce-os-udp) --- # Recipes Source: https://help.1nce.com/docs/blueprints-examples/recipes/ ## Quectel Quectel is a leading provider of cellular and GNSS modules, with a wide range of products available. Here are some resources to help you get started with Quectel modules using our 1NCE services: [Quectel BG95](/docs/blueprints-examples/quectel-bg95-m3) [Quectel EC25 & EC21](/docs/blueprints-examples/quectel-ec25-ec21) ## SIMCOM SIMCOM is a global provider of wireless modules and solutions, offering a range of products for different applications. Here are some resources to help you get started with SIMCOM modules using 1NCE services: [SIMCOM7020E](/docs/blueprints-examples/simcom-7020g-simcom800l) [SIM7000G](/docs/blueprints-examples/sim7000g) ## UBlox u-blox is a leading provider of positioning and wireless communication technologies for the automotive, industrial, and consumer markets. Here are some resources to help you get started with u-blox modules using 1NCE services: [SARA-R410M](/docs/blueprints-examples/sara-r410m) ## Others - 📶 [WvDial Tutorial](/docs/blueprints-examples/wvdial-tutorial) **1NCE VPN** establishes a secure and encrypted tunnel between your device and the VPN server. This ensures that your online activities, such as communication, are protected from eavesdropping, hacking, and surveillance. - 🖥️ [1NCE VPN Linux Client](/docs/blueprints-examples/1nce-vpn-linux-client) --- # SARA-R4 GET HTTP Source: https://help.1nce.com/docs/blueprints-examples/sara-r4-get-http/ ```powershell PowerShell // Set APN AT+CGDCONT=1,"IP","iot.1nce.net" OK AT+CGACT=1,1 OK // Configure HTTP parameters AT+UHTTP=0 OK AT+UHTTP=1,1,"https://www.example.com" OK AT+UHTTP=2,1 OK AT+UHTTP=3,0,"User-Agent: MyClient" OK // Initiate HTTP GET request AT+UHTTPC=0,5,"/api/data" OK // Read HTTP response AT+UHTTPC=0,6 +UHTTPCR: 0,200,185 OK // Retrieve response data AT+URDFILE="response.txt",185 OK // Close HTTP connection AT+UHTTP=0 OK ``` # Preparation Open a serial terminal and connect to the SARA-R4 module using the AT command interface. # Network Registration Ensure that the module is registered to the cellular network if not, check the recipe SARA-R Network registration # Configure the APN # Activate PDP context This command activates the PDP (Packet Data Protocol) context for data communication. # Configure HTTP parameters AT+UHTTP=0: This command initializes the HTTP profile. It prepares the module for HTTP communication. AT+UHTTP=1,1,"``": Here, you need to replace `` with the URL of the web page you want to retrieve. This parameter sets the URL for the HTTP request. AT+UHTTP=2,1: This command configures the HTTP method. The value 1 specifies that you want to use the GET method. If you want to use a different method like POST, you can adjust the value accordingly. AT+UHTTP=3,0,"``": This optional parameter allows you to include request headers in the HTTP request. Request headers provide additional information to the server. For example, you can set the User-Agent header to specify the client making the request. `` should be replaced with the desired request header. For example, you can use "User-Agent: MyClient" to set the User-Agent header to "MyClient". You can include multiple request headers by separating them with line breaks ("\r\n"). # Initiate the HTTP GET request The 5 represents the timeout value in seconds. # Read the HTTP response # Retrieve the response data # Close the HTTP connection # Warp Up Please note that the actual AT command set and syntax may vary based on the specific firmware version and configuration of your SARA-R410M module. Refer to the u-blox documentation and AT command guide for your specific module version for accurate and detailed command information. --- # SARA-R410M 1NCE OS UDP Source: https://help.1nce.com/docs/blueprints-examples/sara-r410m-1nce-os-udp/ ```powershell PowerShell > AT+USOCR=17 +USOCR: 0 OK /*IP address of udp.os.1nce.com for this example is 10.60.8.90 */ > AT+USOST=0,"10.60.8.90",4445,18,"Hello from 1NCE OS" +USOST: 0,18 OK > AT+USOCL=0 OK ``` # Preparation Configure the SARA-R410M module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # create a new socket for communication The module will respond with the socket identifier (socket ID) if the command is successful. # Send the message to 1NCEOS This command would send the string "Hello from 1NCE OS" over socket ID 0 to the remote server with the IP address "10.60.8.90" on port 4445. response indicates that the "AT+USOST" command was successful, and it provides the socket ID and the number of bytes sent. # Close the Socket This command would close the socket connection with socket ID 0. After sending the command, the module should respond with an "OK" response indicating that the socket was successfully closed. --- # SARA-R410M Network Registration Source: https://help.1nce.com/docs/blueprints-examples/sara-r410m-network-registration/ ```powershell PowerShell > AT OK > AT+CFUN? +CFUN: 1 OK > AT+CFUN=1 OK > AT+CPIN? +CPIN: READY OK > AT+ICCID ICCID: 8988XXXX66602XXX3347 > ATI Manufacturer: u-blox Model: SARA-R410M-02B Revision: L0.0.00.00.05.06 [Feb 03 2018 13:00:41] SVN: 02 IMEI: 352753097892796 OK > ATI9 L0.0.00.00.05.06,A.02.01 OK > AT+CEREG=1 OK > AT+COPS=0 OK > AT+CEREG? +CEREG: 1,5 OK +CEREG: 2 +CEREG: 3 +CEREG: 5 > AT+CGDCONT= 1,"IP","iot.1nce.net","10.209.106.8",0,0,0,0 OK ``` # Preparation For testing purposes, connect the SARA-R410M to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # Check your ICCID The ICCID is a unique identifier that is assigned to every SIM card and is used to identify and authenticate the card with the mobile network. N.B: your ICCID without the last digit "7" # Check the modem version to request the firmware revision identification of a module. When you send this command to a module, it will respond with information about the firmware version and other details. # Enable network registration status reports When enabled, the module will report its current registration status to the host device whenever it changes. # Automatic network selection In this mode, the module will scan all available networks and automatically select the one with the strongest signal. # Check the network registration status The response to these commands indicates different registration status. # Set the APN set the Access Point Name (APN) for the network connection. --- # SARA-R410M Source: https://help.1nce.com/docs/blueprints-examples/sara-r410m/ SARA-R410M AT command interface defaults to the GSM character set. Developers could understand and develop applications quickly and efficiently based on these recipes. # Network Registration: - 🦉 [SARA-R410M Network Registration](/docs/blueprints-examples/sara-r410m-network-registration) # SARA-R410M HTTP GET - 🦉 [SARA-R4 GET HTTP](/docs/blueprints-examples/sara-r4-get-http) # 1NCE OS UDP - 🦉 [SARA-R410M 1NCE OS UDP](/docs/blueprints-examples/sara-r410m-1nce-os-udp) --- # SIM7000G 1NCE OS COAP Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-1nce-os-coap/ ```powershell PowerShell AT+CNACT=1,"iot.1nce.net" OK +APP PDP: ACTIVE AT+CCOAPINIT OK AT+CCOAPURL="coap://coap.os.1nce.com:5683" OK AT+CCOAPPARA=code,1,type,"NON",uri-query,0,"t=1",payload,0,"hello world" OK AT+CCOAPACTION +CCOAPACTION: 0,1 OK +CCOAPRECV: 1,14,9 AT+CCOAPACTION=4 +CCOAPACTION: 4,1,1 OK AT+CCOAPHEAD=1,1 +CCOAPHEAD: 1,1,2,0,4.04,1,,,,,,,0,,,,,,,,,,, OK AT+CCOAPREAD=1 +CCOAPREAD: 5,Not Found OK AT+CCOAPTERM OK AT+CNACT=0 OK +APP PDP: ACTIVE ``` # Preparation Configure the SIM7000 module with the appropriate network settings, operator ID, and ensure that it is connected to the cellular network. # Open data connection Open data connection, the parameter is APN. This parameter needs to set different APN values according to 1nce sim card. # Create CoAP object To create a CoAP object, one can use the CoAP Client destination we use AT+CCOAPINIT # Configure CoAP URL Use the AT+CCOAPURL command to setup a URL and establish a connection with the 1NCE endpoint. # Assembling CoAP data packet Assembling CoAP data packet with these parameters code,`` type,(("CON"),("NON"),("ACK"),("RST")) mid,`` token, ((0-ascii code),(1-hex code)),`` content-format,`` accept,`` uri-path,((0-ascii code),(1-hex code)),`` uri-query, ((0-ascii code),(1-hex code)),`` etag, ((0-ascii code),(1-hex code)),`` observe,`` max-age,`` size,`` payload, ((0-ascii code),(1-hex code)),`` # Send Data Received data, Message id is 1, data lengthis14bytes, data payload is 9 bytes # Get receive queen The current receive queue has a total of 1datapacket, and the first packet id is 1. # Read header Read the packet header with messageidof 1and print it parsed # Read the recieve Read the receive packet payload with messageid of 1. The total byte length is 9 and the content is Not Found. # Delete CoAP Object # Disconnect data connection --- # SIM7000G 1NCE OS UDP Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-1nce-os-udp/ ```powershell PowerShell AT+CIPSTART="UDP","udp.os.1nce.com","4445" OK CONNECT OK AT+CIPSEND > welcome to 1nce os SEND OK This is a UDP response message from my server! AT+CIPCLOSE CLOSE OK AT+CIPSHUT SHUT OK ``` # Preparation Configure the SIM7000G module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # Start a UDP Connection A UDP connection towards a server with a given UDP port can be started with 'AT+CIPSTART=...'. The AT Command needs to list the UDP protocol, the target URL or IP and the used UDP Port. If the connection is successfully opened, 'CONNECT OK' is returned. # Send UDP Data With 'AT+CIPSEND' the data send mode is activated. Any input send to the modem will be forwarded via the UDP connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the SIM7000G. The modem will acknowledge the sent message with 'SEND OK'. # Receive UDP Data By default, the modem will forward any incomming UDP data while the connection is open to the serial output interface. # Close UDP Connection An active UDP connection can be closed with 'AT+CIPCLOSE'. The modem will close the UDP connection and respond with 'CLOSE OK'. # Close Data Session To close the entire data session that was opened with 'AT+CIICR', 'AT+CIPSHUT' needs to be used. The command will respond with 'SHUT OK'. Afterwards a new session can be started at any point. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to send and receive data using a UDP connection. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G FTP GET Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-ftp-get/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+SAPBR=3,1,"APN","iot.1nce.net" OK > AT+SAPBR=1,1 OK > AT+SAPBR=2,1 +SAPBR: 1,1,"x.x.x.x" OK > AT+FTPCID=1 OK > AT+FTPSERV="x.x.x.x" OK > AT+FTPUN="" OK > AT+FTPPW="" OK > AT+FTPGETNAME="" OK > AT+FTPGETPATH="/" OK > AT+FTPGET=1 OK +FTPGET: 1,1 > AT+FTPGET=2,1024 +FTPGET: 2,50 01234567890123456789012345678901234 567890123456789 OK > AT+FTPGET=2,1024 +FTPGET: 2,0 OK +FTPGET: 1,1 > AT+FTPGET=2,1024 +FTPGET: 2,1024 01234567890123456789012345678901234 5678901234567890…..1234 OK +FTPGET:1,0 > AT+SAPBR=0,1 OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the HTTP Data Session. Using the 'AT+SAPBR=3,1,"APN","iot.1nce.net"' command specifically for the SIM7000G HTTP mode the 1NCE APN can be set. # Activate PDP Data Session The PDP data session needs to be activated by calling 'AT+SAPBR=1,1', which will activate PDP context with CID 1. # Check PDP Data Session With 'AT+SAPBR=2,1' the status and IP of the PDP data session can be checked. # Set FTP Session Profile Setup the FTP session by setting the PDP session id to the used index. In the example, profile '1' is used. # Set FTP Server IP Set the IP address of the FTP server to which the modem should connect to. # Set FTP Server Username Specify the username used to login into the FTP server. # Set FTP Server Password Set the password needed to access the FTP server. # Set FTP Filename List the filename of the file which should be downloaded from the FTP server. # Set FTP Server Path Configure the path on the FTP where to find the file which should be downloaded. # Start FTP Download Use 'AT+FTPGET=1' to start the download process. '+FTPGET: 1,1' indicates that the downloaded data is available. # Read Downloaded File With 'AT+FTPGET=2,1024' parts of the downloaded file can be read in sections. '+FTPGET: 2,50' indicates the length of available data. # Deactivate PDP Data Session The PDP data session can be closed with 'AT+SAPBR=0,1' if it is not needed anymore. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to make a HTTP GET request. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G HTTP GET Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-http-get/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+SAPBR=3,1,"APN","iot.1nce.net" OK > AT+SAPBR=1,1 OK > AT+SAPBR=2,1 +SAPBR: 1,1,"x.x.x.x" OK > AT+HTTPINIT OK > AT+HTTPPARA? +HTTPPARA: CID: 1 URL: UA: SIMCOM_MODULE PROIP: 0.0.0.0 PROPORT: 0 REDIR: 0 BREAK: 0 BREAKEND: 0 TIMEOUT: 120 CONTENT: USERDATA: OK > AT+HTTPPARA="URL","www.google.de" OK > AT+HTTPACTION=0 OK +HTTPACTION: 0,200,12796 > AT+HTTPHEAD +HTTPHEAD: 628 http/1.1 200 ok date: tue, 22 jun 2021 ... OK > AT+HTTPREAD +HTTPREAD: 12796 AT+HTTPTERM OK > AT+SAPBR=0,1 OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the HTTP Data Session. Using the 'AT+SAPBR=3,1,"APN","iot.1nce.net"' command specifically for the SIM7000G HTTP mode the 1NCE APN can be set. # Activate PDP Data Session The PDP data session needs to be activated by calling 'AT+SAPBR=1,1', which will activate PDP context with CID 1. # Check PDP Data Session With 'AT+SAPBR=2,1' the status and IP of the PDP data session can be checked. # Initialize HTTP The HTTP function of the SIM7000G needs to be initialized using 'AT+HTTPINIT'. If HTTP was already initialized, this command will return an error that can be ignored. # Check HTTP Parameters The parameters of the HTTP function can be checked with 'AT+HTTPPARA?'. These stored variables will be used whenever a function of the HTTP pool is executed. # Set HTTP URL The request URL parameter can be set using 'AT+HTTPPARA="URL","www.google.de"'. In the shown case we will use Google as a target for the HTTP GET request. # Execute HTTP GET A HTTP GET request can be executed using 'AT+HTTPACTION=0'. The 0 indicates a GET request, but can be changed to other HTTP request types. The response '+HTTPACTION: 0,200,12796' shows the HTTP response code and the amount of data received. # Get HTTP Head The head of the HTTP response can be queried with 'AT+HTTPHEAD'. This will return the HTTP head of the response (shorted here). # Get HTTP Body The body of the response can be queried using 'AT+HTTPREAD'. This will return the full body of the response (shorted here). # Terminate HTTP Service Use 'AT+HTTPTERM' to terminate the HTTP service of the SIM7000G. # Deactivate PDP Data Session The PDP data session can be closed with 'AT+SAPBR=0,1' if it is not needed anymore. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to make a HTTP GET request. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G HTTP POST Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-http-post/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+SAPBR=3,1,"APN","iot.1nce.net" OK > AT+SAPBR=1,1 OK > AT+SAPBR=2,1 +SAPBR: 1,1,"x.x.x.x" OK > AT+HTTPINIT OK > AT+HTTPPARA? +HTTPPARA: CID: 1 URL: UA: SIMCOM_MODULE PROIP: 0.0.0.0 PROPORT: 0 REDIR: 0 BREAK: 0 BREAKEND: 0 TIMEOUT: 120 CONTENT: USERDATA: OK > AT+HTTPPARA="URL","" OK > AT+HTTPDATA=100,10000 > <100_bytes_data> OK > AT+HTTPACTION=1 OK +HTTPACTION: 1,200,0 > AT+HTTPTERM OK > AT+SAPBR=0,1 OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the HTTP Data Session. Using the 'AT+SAPBR=3,1,"APN","iot.1nce.net"' command specifically for the SIM7000G HTTP mode the 1NCE APN can be set. # Activate PDP Data Session The PDP data session needs to be activated by calling 'AT+SAPBR=1,1', which will activate PDP context with CID 1. # Check PDP Data Session With 'AT+SAPBR=2,1' the status and IP of the PDP data session can be checked. # Initialize HTTP The HTTP function of the SIM800L needs to be initialized using 'AT+HTTPINIT'. If HTTP was already initialized, this command will return an error that can be ignored. # Check HTTP Parameters The parameters of the HTTP function can be checked with 'AT+HTTPPARA?'. These stored variables will be used whenever a function of the HTTP pool is executed. # Set HTTP URL The POST request URL parameter can be set using 'AT+HTTPPARA="URL","``"'. # Set HTTP POST Data The data to be posted via the HTTP POST request needs to be send to the modem in advance. Using 'AT+HTTPDATA=100,10000', enables the send mode. The SIM7000G waits for 100 bytes of data in the next 10000 ms. The POST data is saved for the request execution. # Execute HTTP POST A HTTP POST request can be executed using 'AT+HTTPACTION=1'. The 1 indicates a POST request. The response '+HTTPACTION: 1,200,0' shows the HTTP response code and the amount of data received. # Terminate HTTP Service Use 'AT+HTTPTERM' to terminate the HTTP service of the SIM7000G. # Deactivate PDP Data Session The PDP data session can be closed with 'AT+SAPBR=0,1' if it is not needed anymore. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to make a HTTP GET request. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G ICMP Ping Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-icmp-ping/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+CSTT="iot.1nce.net","","" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPPING="www.1nce.net" +CIPPING: 1,"142.250.186.99",1,112 +CIPPING: 2,"142.250.186.99",1,112 +CIPPING: 3,"142.250.186.99",1,112 +CIPPING: 4,"142.250.186.99",1,112 > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CSTT="iot.1nce.net","",""' command the 1NCE APN can be set. # Start PDP Session With 'AT+CIICR' a new PDP session is started. A PDP data session is needed to transfer any sort of data. # Get IP Address With 'AT+CIFSR' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # ICMP Ping After the successful setup of the data session, with 'AT+CIPPING="www.1nce.net"' any URL or IP address can be pinged. The responses '+CIPPING: 1,"142.250.186.99",1,112' show the resolved IP address and the ping time. # Data Session Close With 'AT+CIPSHUT' the entire PDP data session of the modem is closed. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to get an ICMP Ping request working. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G MO-SMS Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-mo-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+CMGF=1 OK > AT+CSCS="GSM" OK > AT+CMGS="+49123456" > Test SMS > 1A // HEX-Encoded followed by Newline +CMGS: 25 OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Select SMS Format Specify the SMS format to 'Text Mode' using 'AT+CMGF=1' # Start MO-SMS Message Start the MO-SMS message by calling 'AT+CMGS="+49123456". This will start the SMS text mode to send a message. The target phonenumber can be left empty or filled with any number. The 1NCE SMS Service ignores this number and forwards the SMS via the SMS Forwarder. The command will not return an OK response, it waits for the message input. # Write MO-SMS Message The modem is now in the text mode an will accept ASCII Numeric values for the SMS. It will not return any response until the message is finished. Please keep the SMS size limitations in mind. # Finish MO-SMS Message To finish, exit the text mode and send the SMS message, '1a' needs to be send encoded as HEX towards the modem. The modem will respond with '+CMGS: ``' and an OK if successful. # Wrap Up The MO-SMS was sent and can be received with the 1NCE SMS Forwarding service or viewed in the 1NCE Portal. --- # SIM7000G MT-SMS Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-mt-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK +CMTI: "SM",1 +CMTI: "SM",2 > AT+CMGL="ALL" +CMGL: 1,"REC UNREAD","123","","21/06/22,10:13:29+00" MT-SMS 01 Test +CMGL: 2,"REC UNREAD","123","","21/06/22,10:13:45+00" MT-SMS 02 OK > AT+CMGR=1,0 +CMGR: "REC READ","123","","21/06/22,10:13:29+00" MT-SMS 01 Test OK > AT+CMGD=1,0 OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Issue MT-SMS A SMS destined for a specifc device with a 1NCE SIM can be send using the Connectivity Management Platform website or through an API call. See the Developer Hub Guide for how to issue a MT-SMS. A SMS can be send while the device is not connected to the network. It will be delivered and received as soon as the device reconnects to the network. In this example, the source address was '123'. # Receive MT-SMS After connecting to the network, wait until the issued MT-SMS is received by the device. By default this is indicated by '+CMTI: "SM",``' returned from the SIM7000G. # Read All MT-SMS All SMS messages stored can be listed through 'AT+CMGL="ALL"'. The 'ALL' parameter can be changed according to the AT Command manual. # Read Specific MT-SMS One specific MT-SMS can be read using 'AT+CMGR=``,0', where the `` is the storage id of the message of interest. # Delete Specific MT-SMS Stored SMS messages can be deleted using 'AT+CMGD=``,0' # Wrap Up MT-SMS messages issued through the API of 1NCE portal, received by the SIM7000G can be read using a few simple AT Commands. Setting up the APN is not required for using SMS. --- # SIM7000G Network Registration Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-network-registration/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=? +COPS: (1,"Telekom.de","TDG","26201",0),(1,"Vodafone.de","Vodafone","26202",0),(1,"o2 - de","o2 - de","26203",0),(2,"o2 - de","o2 - de","26203",7),(1,"o2 - de","o2 - de","26203",9),(1,"Vodafone.de","Vodafone","26202",9),(1,"Telekom.de","TDG","26201",9),,(0,1,2,3,4),(0,) OK > AT+COPS=0,0 OK > AT+COPS=4,2,"26202" OK > AT+COPS=1,2,"26201" OK > AT+COPS? +COPS: 1,2,"26201",9 OK > AT+CPSI? +CPSI: LTE NB-IOT,Online,262-01,0xE2A4,37356039,446,EUTRAN-BAND8,3740,0,0,-3,-100,-96,15 > AT+COPS=3,0 OK > AT+COPS? +COPS: 1,0,"D1" OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Query Use 'AT+COPS=?' to query all Public Land Mobile Networks that can be received with the SIM7000G at the given location. Note this scan for operators can take some time to respond. In the returned result, all avaliable network operators are listed with the long, short an numeric identifiers and avaliable Radio Access Technologies. # PLMN Automatic Selection To let the SIM7000G automatically choose which operator to connect to, issue 'AT+COPS=0,0'. This sets the registration process to automatic. The preferred RAT selection will still apply. # PLMN Manual/Automatic Selection Manual operator selection with a fallback to automatic is a good choice to ensure automatic failover in case of an outage. With 'AT+COPS=4,2,"26202"', manual/automatic mode (4) is selected and the numeric identifier setting (2) is used to set operator (26202). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Manual Selection Manual operator selection without a fallback to automatic is generally not recommended due to the missing failover in case of an outage. With 'AT+COPS=1,2,"26201"', manual mode (1) is selected and the numeric identifier setting (2) is used to set operator (26201). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Connection Process After setting a registration process with 'AT+COPS=...', the modem will try to connect to the Public Land Mobile Network. This can take some time to respond with 'OK'. Afterwards, the connection can be checked with 'AT+COPS?' and 'AT+CGREG?' for GSM or 'AT+CEREG?' for LTE as usual. 'AT+CPSI?' can also be used to check the current connection. # PLMN Format Selection The format of the current operator listing returned by 'AT+COPS?' can be set with 'AT+COPS=3,``'. Valid formats are (0) long, (1) short, (2) numeric. # Wrap Up The SIM7000G can be configured for manual, automatic or manual/automatic network registration. For more details see the SIM700G AT Command manual from the manufacturer. --- # SIM7000G RAT Configuration Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-rat-configuration/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+CNMP=? +CNMP: ((2-Automatic),(13-GSM Only),(38-LTE Only),(51-GSM And LTE Only)) OK > AT+CNMP? +CNMP: 2 OK > AT+CMNB=? +CMNB: ((1-Cat-M),(2-NB-IoT),(3-Cat-M And NB-IoT)) OK > AT+CMNB? +CMNB: 3 OK > AT+CBANDCFG=? +CBANDCFG: (CAT-M,NB-IOT),(1,2,3,4,5,8,12,13,17,18,19,20,26,28,39) OK > AT+CBANDCFG? +CBANDCFG: "CAT-M",20,8 +CBANDCFG: "NB-IOT",20,8 OK > AT+CNMP=2 OK > AT+CMNB=3 OK > AT+CBANDCFG="CAT-M",20,8 OK > AT+CBANDCFG="NB-IOT",20,8 OK > AT+CFUN=0 +CPIN: NOT READY OK > AT+CFUN=1 OK +CPIN: READY SMS Ready ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # Query Available RAT Configurations The SIM7000G can use the Radio Access Technologies (RAT) LTE Cat-M, NB-IoT and 2G. The avaliable RAT selections can be listed with 'AT+CNMP=?'. The currently configured RAT setting can be viewed with 'AT+CNMP?'. # Query LTE RAT Configurations When using NB-IoT and/or LTE Cat-M, the available RAT selections can be listed with 'AT+CMNB=?'. The currently configured LTE RAT setting can be viewed with 'AT+CMNB?'. # Query LTE Bands Configurations For using LTE, different default bands can be configured for NB-IoT and Cat-M. This will speed up the search and connection process. Use 'AT+CBANDCFG=?' to list all available band configurations. The configured Bands can be viewed with 'AT+CBANDCFG?'. # Set Default RAT For these guides, the '2-Automatic' RAT selection will be configured with 'AT+CNMP=2'. # Set Preferred LTE RAT The preferred LTE RAT will be set to both NB-IoT and Cat-M using 'AT+CMNB=3'. # Set LTE Bands In Germany, the commonly used LTE bands for NB-IoT and Cat-M are 20 and 8. Therefore, these bands are configured to speed up the search and connection process. For other countries, the band selection might be different. Please feel free to ask the 1NCE support for the best LTE bands in the desired region. # Apply Change To force the application of a configuration change, a cycling of the modem functionality helps to apply the new configuration. # Wrap Up This guide showed the basic RAT configuration for a SIM7000G with a 1NCE SIM. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G TCP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-tcp-client-connection/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+CSTT="iot.1nce.net","","" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPSTART="TCP","", OK CONNECT OK > AT+cipsend > > 1a SEND OK This is a TCP response message from my server! > AT+CIPCLOSE CLOSED > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CSTT="iot.1nce.net","",""' command the 1NCE APN can be set. # Start PDP Session With 'AT+CIICR' the PDP Session is started. # Get IP Address With 'AT+CIFSR' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # Start a TCP Connection A TCP connection towards a server with a given TCP port can be started with 'AT+CIPSTART=...'. The AT Command needs to list the TCP protocol, the target URL or IP and the used TCP Port. If the connection is successfully opened, 'CONNECT OK' is returned. # Send TCP Data With 'AT+CIPSEND' the data send mode is activated. Any input send to the modem will be forwarded via the tcp connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the SIM7000G. The modem will acknowledge the sent message with 'SEND OK'. # Receive TCP Data By default, the modem will forward any incomming TCP data while the connection is open to the serial output interface. # Close TCP Connection An active TCP connection can be closed with 'AT+CIPCLOSE'. The modem will close the TCP connection and respond with 'CLOSED'. # Close Data Session To close the entire data session that was opened with 'AT+CIICR', 'AT+CIPSHUT' needs to be used. The command will respond with 'SHUT OK'. Afterwards a new session can be started at any point. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to send and receive data using a TCP connection. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G UDP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/sim7000g-udp-client-connection/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CEREG? +CREG: 0,2 OK > AT+CEREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CGREG? +CREG: 0,5 OK > AT+CPSI? +CPSI: GSM,Online,262-01,0x972d,5559,79 EGSM 900,-83,0,24-24 > AT+COPS? +COPS: 0,0,"Telekom.de 1nce.net",3 OK > AT+CSTT="iot.1nce.net","","" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPSTART="UDP","", OK CONNECT OK > AT+cipsend > > 1a SEND OK This is a UDP response message from my server! > AT+CIPCLOSE CLOSED > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM7000G (1529B05SIM7000G) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CEREG?' or 'AT+CGREG?' the network registration status can be queried denpendent on the used RAT (LTE or GSM). '+C(E/G)REG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+C(E/G)REG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM7000G and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+CPSI?' the RAT and current status of the connection can be viewed. Futher, with 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CSTT="iot.1nce.net","",""' command the 1NCE APN can be set. # Start PDP Session With 'AT+CIICR' the PDP Session is started. # Get IP Address With 'AT+CIFSR' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # Start a UDP Connection A UDP connection towards a server with a given UDP port can be started with 'AT+CIPSTART=...'. The AT Command needs to list the UDP protocol, the target URL or IP and the used UDP Port. If the connection is successfully opened, 'CONNECT OK' is returned. # Send UDP Data With 'AT+CIPSEND' the data send mode is activated. Any input send to the modem will be forwarded via the UDP connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the SIM7000G. The modem will acknowledge the sent message with 'SEND OK'. # Receive UDP Data By default, the modem will forward any incomming UDP data while the connection is open to the serial output interface. # Close UDP Connection An active UDP connection can be closed with 'AT+CIPCLOSE'. The modem will close the UDP connection and respond with 'CLOSED'. # Close Data Session To close the entire data session that was opened with 'AT+CIICR', 'AT+CIPSHUT' needs to be used. The command will respond with 'SHUT OK'. Afterwards a new session can be started at any point. # Wrap Up This guide showed the basic setup of a SIM7000G with a 1NCE SIM to send and receive data using a UDP connection. For more details and documentation please refer to the AT Command manual of the SIM7000G. --- # SIM7000G Source: https://help.1nce.com/docs/blueprints-examples/sim7000g/ SIM7000G AT command interface defaults to the GSM character set. Developers could understand and develop applications quickly and efficiently based on these recipes. # SIM7000G RAT Configuration Setup and configure the Quectel EC25 or EC21 for use with 1NCE SIM. - 📲 [SIM7000G RAT Configuration](/docs/blueprints-examples/sim7000g-rat-configuration) # Network Registration: Network registration is the process by which a cellular device connects to a cellular network and obtains the necessary credentials to access the network's services. This process involves several steps, including network selection, authentication, and registration. - 📲 [SIM7000G Network Registration](/docs/blueprints-examples/sim7000g-network-registration) # ICMP Ping Connect with the SIM7000G to a mobile network, start a data session, and issue an ICMP Ping request. - 📲 [SIM7000G ICMP Ping](/docs/blueprints-examples/sim7000g-icmp-ping) # MO-SMS Send an SMS message from a sim7000G to the 1NCE SMS Forwarding Service. - 📲 [SIM7000G MO-SMS](/docs/blueprints-examples/sim7000g-mo-sms) # MT-SMS Receive SMS messages with a Sim7000G - 📲 [SIM7000G MT-SMS](/docs/blueprints-examples/sim7000g-mt-sms) # TCP Client Connect to a TCP Server and send/receive data using a SIM7000g. - 📲 [SIM7000G TCP Client Connection](/docs/blueprints-examples/sim7000g-tcp-client-connection) # 1NCE OS UDP Protocol - 📲 [SIM7000G UDP Client Connection](/docs/blueprints-examples/sim7000g-udp-client-connection) # 1NCE OS CoAP Protocol - 🦉 [SIM7020E 1NCE OS CoAP](/docs/blueprints-examples/sim7020e-1nce-os-coap-1) --- # SIM7020E 1NCE OS CoAP Source: https://help.1nce.com/docs/blueprints-examples/sim7020e-1nce-os-coap-1/ ```curl cURL /*Create client instance with coap.os.1nce.com via IP address*/ > AT+CCOAPNEW="10.60.2.219",5683,1 +CCOAPNEW: 1 OK /*Send hex data to server Hi 1NCEOS */ > AT+CCOAPCSEND=1,1,0,0,2,,,9,"486920314E43454F53" /* Release Client instance */ > AT+CCOAPDEL=1 OK ``` ```json Response Example {"success":true} ``` # Preparation Configure the SIM7020E module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # Create CoAP Client Creates a new CoAP client instance with the 1NCEOS endpoint and port number 5683 # Send CoAP data Sends a CoAP message to the server using the client instance created in the previous command. The first parameter "1" specifies the client instance ID. The second parameter "1" specifies the CoAP method (GET, POST, etc.). The third and fourth parameters are the message ID and token, respectively. The fifth parameter "2" specifies the CoAP message type (CON, NON, ACK, RST). The eighth parameter "9" specifies the length of the payload in bytes. The ninth parameter is the payload itself, which is the hex-encoded string "486920314E43454F53" (which translates to "Hi 1NCEOS" in ASCII). # Release the CoAP Client instance Releases the CoAP client instance with ID "1", freeing up any resources associated with it. --- # SIM7020E 1NCE OS CoAP Source: https://help.1nce.com/docs/blueprints-examples/sim7020e-1nce-os-coap/ ```powershell PowerShell /*Create client instance with coap.os.1nce.com via IP address*/ > AT+CCOAPNEW="10.60.2.219",5683,1 +CCOAPNEW: 1 OK /*Send hex data to server Hi 1NCEOS */ > AT+CCOAPCSEND=1,1,0,0,2,,,9,"486920314E43454F53" /* Release Client instance */ > AT+CCOAPDEL=1 OK ``` # Preparation Configure the SIM7020E module with the appropriate network settings, such as the APN and operator ID, and ensure that it is connected to the cellular network. # Create CoAP Client creates a new CoAP client instance with the 1nce os endpoint and port number 5683 # Send CoAP data sends a CoAP message to the server using the client instance created in the previous command. The first parameter "1" specifies the client instance ID. The second parameter "1" specifies the CoAP method (GET, POST, etc.). The third and fourth parameters are the message ID and token, respectively. The fifth parameter "2" specifies the CoAP message type (CON, NON, ACK, RST). The eighth parameter "9" specifies the length of the payload in bytes. The ninth parameter is the payload itself, which is the hex-encoded string "486920314E43454F53" (which translates to "Hi 1NCEOS" in ASCII). # Release the CoAP Client instance releases the CoAP client instance with ID "1", freeing up any resources associated with it. --- # SIM800L HTTP GET Source: https://help.1nce.com/docs/blueprints-examples/sim800l-http-get/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+SAPBR=3,1,"APN","iot.1nce.net" OK > AT+SAPBR=1,1 OK > AT+SAPBR=2,1 +SAPBR: 1,1,"x.x.x.x" OK > AT+HTTPINIT OK > AT+HTTPPARA? +HTTPPARA: CID: 1 URL: UA: SIMCOM_MODULE PROIP: 0.0.0.0 PROPORT: 0 REDIR: 0 BREAK: 0 BREAKEND: 0 TIMEOUT: 120 CONTENT: USERDATA: OK > AT+HTTPPARA="URL","www.google.de" OK > AT+HTTPACTION=0 OK +HTTPACTION: 0,200,12796 > AT+HTTPHEAD +HTTPHEAD: 628 http/1.1 200 ok date: tue, 22 jun 2021 ... OK > AT+HTTPREAD +HTTPREAD: 12796 AT+HTTPTERM OK > AT+SAPBR=0,1 OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Configure APN Next, the APN needs to be set for the HTTP Data Session. Using the 'AT+SAPBR=3,1,"APN","iot.1nce.net"' command specifically for the SIM800L HTTP mode the 1NCE APN can be set. # Activate PDP Data Session The PDP data session needs to be activated by calling 'AT+SAPBR=1,1', which will activate PDP context with CID 1. # Check PDP Data Session With 'AT+SAPBR=2,1' the status and IP of the PDP data session can be checked. # Initialize HTTP The HTTP function of the SIM800L needs to be initialized using 'AT+HTTPINIT'. If HTTP was already initialized, this command will return an error that can be ignored. # Check HTTP Parameters The parameters of the HTTP function can be checked with 'AT+HTTPPARA?'. These stored variables will be used whenever a function of the HTTP pool is executed. # Set HTTP URL The request URL parameter can be set using 'AT+HTTPPARA="URL","www.google.de"'. In the shown case we will use Google as a target for the HTTP GET request. # Execute HTTP GET A HTTP GET request can be executed using 'AT+HTTPACTION=0'. The 0 indicates a GET request, but can be changed to other HTTP request types. The response '+HTTPACTION: 0,200,12796' shows the HTTP response code and the amount of data received. # Get HTTP Head The head of the HTTP response can be queried with 'AT+HTTPHEAD'. This will return the HTTP head of the response (shorted here). # Get HTTP Body The body of the response can be queried using 'AT+HTTPREAD'. This will return the full body of the response (shorted here). # Terminate HTTP Service Use 'AT+HTTPTERM' to terminate the HTTP service of the SIM800L. # Deactivate PDP Data Session The PDP data session can be closed with 'AT+SAPBR=0,1' if it is not needed anymore. # Wrap Up This guide showed the basic setup of a SIM800L with a 1NCE SIM to get a HTTP GET request working. Other HTTP POST, PUT, etc. requests are fairly similar but can include a few more parameters. For more details and documentation please refer to the AT Command manual of the SIM800L. --- # SIM800L HTTP POST Source: https://help.1nce.com/docs/blueprints-examples/sim800l-http-post/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+SAPBR=3,1,"APN","iot.1nce.net" OK > AT+SAPBR=1,1 OK > AT+SAPBR=2,1 +SAPBR: 1,1,"x.x.x.x" OK > AT+HTTPINIT OK > AT+HTTPPARA? +HTTPPARA: CID: 1 URL: UA: SIMCOM_MODULE PROIP: 0.0.0.0 PROPORT: 0 REDIR: 0 BREAK: 0 BREAKEND: 0 TIMEOUT: 120 CONTENT: USERDATA: OK > AT+HTTPPARA="URL","" OK > AT+HTTPDATA=100,10000 > <100_bytes_data> OK > AT+HTTPACTION=1 OK +HTTPACTION: 1,200,0 > AT+HTTPTERM OK > AT+SAPBR=0,1 OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Configure APN Next, the APN needs to be set for the HTTP Data Session. Using the 'AT+SAPBR=3,1,"APN","iot.1nce.net"' command specifically for the SIM800L HTTP mode the 1NCE APN can be set. # Activate PDP Data Session The PDP data session needs to be activated by calling 'AT+SAPBR=1,1', which will activate PDP context with CID 1. # Check PDP Data Session With 'AT+SAPBR=2,1' the status and IP of the PDP data session can be checked. # Initialize HTTP The HTTP function of the SIM800L needs to be initialized using 'AT+HTTPINIT'. If HTTP was already initialized, this command will return an error that can be ignored. # Check HTTP Parameters The parameters of the HTTP function can be checked with 'AT+HTTPPARA?'. These stored variables will be used whenever a function of the HTTP pool is executed. # Set HTTP URL The POST request URL parameter can be set using 'AT+HTTPPARA="URL","``"'. # Set HTTP POST Data The data to be posted via the HTTP POST request needs to be send to the modem in advance. Using 'AT+HTTPDATA=100,10000', enables the send mode. The SIM800L waits for 100 bytes of data in the next 10000 ms. The POST data is saved for the request execution. # Execute HTTP POST A HTTP POST request can be executed using 'AT+HTTPACTION=1'. The 1 indicates a POST request. The response '+HTTPACTION: 1,200,0' shows the HTTP response code and the amount of data received. # Terminate HTTP Service Use 'AT+HTTPTERM' to terminate the HTTP service of the SIM800L. # Deactivate PDP Data Session The PDP data session can be closed with 'AT+SAPBR=0,1' if it is not needed anymore. # Wrap Up This guide showed the basic setup of a SIM800L with a 1NCE SIM to get a HTTP POST request working. Other HTTP GET, PUT, etc. requests are fairly similar but can include a few more parameters. For more details and documentation please refer to the AT Command manual of the SIM800L. --- # SIM800L ICMP Ping Source: https://help.1nce.com/docs/blueprints-examples/sim800l-icmp-ping/ ```c AT-Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+CSTT="iot.1nce.net","","" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPPING="www.1nce.net" +CIPPING: 1,"142.250.186.99",1,112 +CIPPING: 2,"142.250.186.99",1,112 +CIPPING: 3,"142.250.186.99",1,112 +CIPPING: 4,"142.250.186.99",1,112 > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. # Configure APN Next, the APN needs to be set for the Data Session. Using the 'AT+CSTT="iot.1nce.net","",""' command specifically for the SIM800L the 1NCE APN can be set. # Start GPRS Connection With 'AT+CIICR' the GPRS connection is started. # Get IP Address With 'AT+CIFSR' the obtained local IP of the modem can be queried. The response is the IP obtained from the network. # ICMP Ping After the successful setup of the data session, with 'AT+CIPPING="www.1nce.net"' any URL or IP address can be pinged. The responses '+CIPPING: 1,"142.250.186.99",1,112' show the resolved IP address and the ping time. # Data Session Close With 'AT+CIPSHUT' the data session of the modem is closed. # Wrap Up This guide showed the basic setup of a SIM800L with a 1NCE SIM to get an ICMP Ping request working. For more details and documentation please refer to the AT Command manual of the SIM800L. --- # SIM800L MO-SMS Source: https://help.1nce.com/docs/blueprints-examples/sim800l-mo-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+CMGF=1 OK > AT+CSCS="GSM" OK > AT+CMGS="+49123456" > Test SMS > 1A // HEX-Encoded followed by Newline +CMGS: 25 OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Select SMS Format Specify the SMS format to 'Text Mode' using 'AT+CMGF=1' # Start MO-SMS Message Start the MO-SMS message by calling 'AT+CMGS="+49123456". This will start the SMS text mode to send a message. The target phonenumber can be left empty or filled with any number. The 1NCE SMS Service ignores this number and forwards the SMS via the SMS Forwarder. The command will not return an OK response, it waits for the message input. # Write MO-SMS Message The modem is now in the text mode an will accept ASCII Numeric values for the SMS. It will not return any response until the message is finished. Please keep the SMS size limitations in mind. # Finish MO-SMS Message To finish, exit the text mode and send the SMS message, '1a' needs to be send encoded as HEX towards the modem. The modem will respond with '+CMGS: ``' and an OK if successful. # Wrap Up The MO-SMS was sent and can be received with the 1NCE SMS Forwarding service or viewed in the 1NCE Portal. --- # SIM800L MT-SMS Source: https://help.1nce.com/docs/blueprints-examples/sim800l-mt-sms/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+CMGF=1 OK > AT+CSCS="GSM" OK +CMTI: "SM",1 +CMTI: "SM",2 > AT+CMGL="ALL" +CMGL: 1,"REC UNREAD","123","","21/06/22,10:13:29+00" MT-SMS 01 Test +CMGL: 2,"REC UNREAD","123","","21/06/22,10:13:45+00" MT-SMS 02 OK > AT+CMGR=1,0 +CMGR: "REC READ","123","","21/06/22,10:13:29+00" MT-SMS 01 Test OK > AT+CMGD=1,0 OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Set SMS Format Specify the format and RAT for SMS. # Issue MT-SMS A SMS destined for a specifc device with a 1NCE SIM can be send using the Connectivity Management Platform website or through an API call. See the Developer Hub Guide for how to issue a MT-SMS. A SMS can be send while the device is not connected to the network. It will be delivered and received as soon as the device reconnects to the network. In this example, the source address was '123'. # Receive MT-SMS After connecting to the network, wait until the issued MT-SMS is received by the device. By default this is indicated by '+CMTI: "SM",``' returned from the SIM800L. # Read All MT-SMS All SMS messages stored can be listed through 'AT+CMGL="ALL"'. The 'ALL' parameter can be changed according to the AT Command manual. # Read Specific MT-SMS One specific MT-SMS can be read using 'AT+CMGR=``,0', where the `` is the storage id of the message of interest. # Delete Specific MT-SMS Stored SMS messages can be deleted using 'AT+CMGD=``,0' # Wrap Up MT-SMS messages issued through the API of 1NCE portal, received by the SIM800L can be read using a few simple AT Commands. Setting up the APN is not required for using SMS. --- # SIM800L Network Registration Source: https://help.1nce.com/docs/blueprints-examples/sim800l-network-registration/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=? +COPS: (1,"D1","TMO D","26201"),(2,"vodafone","voda D2","26202"),(1,"E-Plus","E-Plus","26203"),,(0-4),(0-2) OK > AT+COPS=0,0 OK > AT+COPS=4,2,"26202" OK > AT+COPS=1,2,"26201" OK > AT+COPS? +COPS: 1,2,"26201" OK > AT+COPS=3,0 OK > AT+COPS? +COPS: 1,0,"D1" OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Query Use 'AT+COPS=?' to query all Public Land Mobile Networks that can be received with the SIM800L at the given location. Note this scan for operators can take some time to respond. In the returned result, all avaliable network operators are listed with the long, short an numeric identifiers. # PLMN Automatic Selection To let the SIM800L automatically choose which operator to connect to, issue 'AT+COPS=0,0'. This sets the registration process to automatic. # PLMN Manual/Automatic Selection Manual operator selection with a fallback to automatic is a good choice to ensure automatic failover in case of an outage. With 'AT+COPS=4,2,"26202"', manual/automatic mode (4) is selected and the numeric identifier setting (2) is used to set operator (26202). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Manual Selection Manual operator selection without a fallback to automatic is generally not recommended due to the missing failover in case of an outage. With 'AT+COPS=1,2,"26201"', manual mode (1) is selected and the numeric identifier setting (2) is used to set operator (26201). The numeric id of the operator needs to be set based on the preferred network from 'AT+COPS=?'. # PLMN Connection Process After setting a registration process with 'AT+COPS=...', the modem will try to connect to the Public Land Mobile Network. This can take some time to respond with 'OK'. Afterwards, the connection can be checked with 'AT+COPS?' and 'AT+CREG?' as usual. # PLMN Format Selection The format of the current operator listing returned by 'AT+COPS?' can be set with 'AT+COPS=3,``'. Valid formats are (0) long, (1) short, (2) numeric. # Wrap Up The SIM800L can be configured for manual, automatic or manual/automatic network registration. For more details see the SIM800L AT Command manual from the manufacturer. --- # SIM800L TCP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/sim800l-tcp-client-connection/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+CSTT="iot.1nce.net","","" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPSTART="TCP","", OK CONNECT OK > AT+cipsend > > 1a SEND OK This is a TCP response message from my server! > AT+CIPCLOSE CLOSED > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Configure APN Next, the APN needs to be set for the TCP Data Session. Using the 'AT+CGDCONT=1,"IP","iot.1nce.net"' command, the 1NCE APN can be set. # Bring Up GPRS After the APN was set, the GPRS connection needs to be activated. # Check IP Address The local IP address of the SIM800L can be checked with 'AT+CIFSR'. This IP should match the statically aissigned 1NCE SIM IP. # Start a TCP Connection A TCP connection towards a server with a given TCP port can be started with 'AT+CIPSTART=...'. The AT Command needs to list the TCP protocol, the target URL or IP and the used TCP Port. If the connection is successfully opened, 'CONNECT OK' is returned. # Send TCP Data With 'AT+CIPSEND' the data send mode is activated. Any input send to the modem will be forwarded via the tcp connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be send to the SIM800L. The modem will acknowledge the sent message with 'SEND OK'. # Receive TCP Data By default, the modem will forward any incomming TCP data while the connection is open to the serial output interface. # Close TCP Connection An active TCP connection can be closed with 'AT+CIPCLOSE'. The modem will close the TCP connection and respond with 'CLOSED'. # Close Data Session To close the entire data session that was opened with 'AT+CIICR', 'AT+CIPSHUT' needs to be used. The command will respond with 'SHUT OK'. Afterwards a new session can be started at any point. # Wrap Up Using the default TCP connection cpabilites of the SIM800L to send and receive data is a fairly easy process. For more advanced features and configurations please refer to the AT Command manual of the SIM800L. --- # SIM800L UDP Client Connection Source: https://help.1nce.com/docs/blueprints-examples/sim800l-udp-client-connection/ ```curl AT Commands > AT OK > AT+CFUN? +CFUN: 1 > AT+CFUN=1 +CPIN: READY OK SMS Ready Call Ready > AT+CPIN? +CPIN: READY OK > AT+COPS=0,0 OK > AT+CREG? +CREG: 0,2 OK > AT+CREG? +CREG: 0,5 OK > AT+COPS? +COPS: 0,0,"D1" OK > AT+CGDCONT=1,"IP","iot.1nce.net" OK > AT+CIICR OK > AT+CIFSR x.x.x.x > AT+CIPSTART="UDP","udp.connectivity-suite.cloud",4445 OK CONNECT OK > AT+cipsend > > 1a SEND OK This is a UDP response message from my server! > AT+CIPCLOSE CLOSED > AT+CIPSHUT SHUT OK ``` # Preperation For testing purposes, connect the SIM800L (1418B05SIM800L24) to a computer. The commands used in this guide will be issued via the serial interface towards the modem. Please setup the specific hardware device that these AT Commands can be sent to the device serial interface. Further ensure that the 1NCE SIM is inserted correctly into the device. # Check Module Communication Check that the module response to a basic 'AT' command. The device should return 'OK' as answer. # Check Functionality Use 'AT+CFUN?' to check the functionality setting of the modem. '+CFUN: 1' should be returned, indicating that the modem is in the full operating mode. # Activate Functionality If the prior command returns '+CFUN: 0', use 'AT+CFUN=1' to activate the full modem functionality. # Check SIM PIN Use 'AT+CPIN?' to check if the SIM is ready to use. As the 1NCE SIM do not have a PIN set by default the modem should return '+CPIN: READY'. If an error is returned, please check the SIM is inserted correctly or try the SIM in a smartphone. # PLMN Selection Use 'AT+COPS=0,0' to set the Public Land Mobile Network selection of the modem to automatic. This will ensure that the modem will pick the best operator based on the currently available selection at the given location. # Network Registration With 'AT+CREG?' the network registration status can be queried. '+CREG: 0,2' indicates that the device is still searching for a network. Use this command to query the status repeatedly until '+CREG: 0,5' indicates that the modem is connected to a network and is roaming. 1NCE SIMs are always roaming as they do not have a home country set for the IoT use case. If the modem does not connect within a couple of minutes, please check the response code in the AT Command manual of the SIM800L and possibly test the SIM in a smartphone to check the coverage. # Check Registered Network With 'AT+COPS?' it can be checked to which network the modem is currently attached. In the shown case the modem is attached to the Telekom Germany network. It is always recommended to check the network registration before running further commands to ensure the modem is connected. # Configure APN Next, the APN needs to be set for the UDP Data Session. Using the 'AT+CGDCONT=1,"IP","iot.1nce.net"' command, the 1NCE APN can be set. # Bring Up GPRS After the APN was set, the GPRS connection needs to be activated. # Check IP Address The local IP address of the SIM800L can be checked with 'AT+CIFSR'. This IP should match the statically aissigned 1NCE SIM IP. # Start a UDP Connection A UDP connection towards a server with a given UDP port can be started with 'AT+CIPSTART=...'. The AT Command needs to list the UDP protocol, the target URL or IP and the used UDP Port. If the connection is successfully opened, 'CONNECT OK' is returned. # Send UDP Data With 'AT+CIPSEND' the data send mode is activated. Any input sends to the modem will be forwarded via the UDP connection. To deactivate the send mode, '1A' encoded as a HEX value needs to be sent to the SIM800L. The modem will acknowledge the sent message with 'SEND OK'. This example is leveraging our 1NCE Data Broker UDP Endpoint. # Receive UDP Data By default, the modem will forward any incomming UDP data while the connection is open to the serial output interface. # Close UDP Connection An active UDP connection can be closed with 'AT+CIPCLOSE'. The modem will close the UDP connection and respond with 'CLOSED'. # Close Data Session To close the entire data session that was opened with 'AT+CIICR', 'AT+CIPSHUT' needs to be used. The command will respond with 'SHUT OK'. Afterwards a new session can be started at any point. # Wrap Up Using the default UDP connection cpabilites of the SIM800L to send and receive data is a fairly easy process. For more advanced features and configurations please refer to the AT Command manual of the SIM800L. --- # SIMCOM 7020G & SIMCOM800L Source: https://help.1nce.com/docs/blueprints-examples/simcom-7020g-simcom800l/ SIMCom SIM7020E is a Multi-Band NB-IoT module solution in a SMT format for the European market. It has strong extension capability with rich interfaces including UART, GPIO etc. The package of SIM7020 is compatible with SIM800C. # Network Registration - 📲 [SIM800L Network Registration](/docs/blueprints-examples/sim800l-network-registration) # ICMP PING - 📲 [SIM800L ICMP Ping](/docs/blueprints-examples/sim800l-icmp-ping) # SIM800L MO-SMS - 📲 [SIM800L MO-SMS](/docs/blueprints-examples/sim800l-mo-sms) # SIM800L MT-SMS - 📲 [SIM800L MT-SMS](/docs/blueprints-examples/sim800l-mt-sms) # SIM800L HTTP GET this functionality used just for SIM800L not SIM7020G - 📲 [SIM800L HTTP GET](/docs/blueprints-examples/sim800l-http-get) # SIM800L HTTP POST - 📲 [SIM800L HTTP POST](/docs/blueprints-examples/sim800l-http-post) # SIM800L & SIM7020G TCP Client - 📲 [SIM800L TCP Client Connection](/docs/blueprints-examples/sim800l-tcp-client-connection) # 1NCE OS UDP Protocol - 📲 [SIM800L UDP Client Connection](/docs/blueprints-examples/sim800l-udp-client-connection) # 1NCE OS CoAP Protocol - 🦉 [SIM7000G 1NCE OS COAP](/docs/blueprints-examples/sim7000g-1nce-os-coap) --- # WvDial Tutorial Source: https://help.1nce.com/docs/blueprints-examples/wvdial-tutorial/ ```powershell Installation > lsusb Bus 001 Device 005: ID 12d1:1001 Huawei Technologies Co., Ltd. E161/E169/E620/E800 HSDPA Modem Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter Bus 001 Device 002: ID 0424:9514 Standard Microsystems Corp. SMC9514 Hub Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub > sudo apt install usb-modeswitch > sudo apt install wvdial ``` ```powershell Configuration > sudo wvdial --> WvDial: Internet dialer version 1.61 --> Initializing modem. --> Sending: ATZ ATZ OK --> Sending: ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0 ATQ0 V1 E1 S0=0 &C1 &D2 +FCLASS=0 OK --> Modem initialized. --> Configuration does not specify a valid phone number. --> Configuration does not specify a valid login name. --> Configuration does not specify a valid password. > sudo nano /etc/wvdial.conf [Dialer 1nce] Init1 = ATZ Init2 = ATQ0 V1 E1 S0=0 &C1 &D2 Init3 = AT+CGDCONT=1,"IP","iot.1nce.net" Modem Type = Analog Modem Baud = 9600 New PPPD = yes Modem = /dev/ttyUSB0 ISDN = 0 Phone = *99# Password = * Username = * ``` ```powershell Connection > sudo wvdial 1nce --> WvDial: Internet dialer version 1.61 --> Initializing modem. --> Sending: ATZ ATZ OK --> Sending: ATQ0 V1 E1 S0=0 &C1 &D2 ATQ0 V1 E1 S0=0 &C1 &D2 OK --> Sending: AT+CGDCONT=1,"IP","iot.1nce.net" AT+CGDCONT=1,"IP","iot.1nce.net" OK --> Modem initialized. --> Sending: ATDT*99# --> Waiting for carrier. ATDT*99# CONNECT --> Carrier detected. Waiting for prompt. --> Starting pppd at Mon Jun 21 10:29:44 2021 --> Pid of pppd: 5027 --> Using interface ppp0 --> local IP address x.x.x.x --> remote IP address x.x.x.x --> primary DNS address 8.8.8.8 --> secondary DNS address 8.8.4.4 > Crtl+C Caught signal 2: Attempting to exit gracefully... --> Terminating on signal 15 --> Connect time 1.5 minutes. --> Disconnecting at Mon Jun 21 10:31:16 2021 ``` ```powershell Interface > ifconfig ppp0: flags=4305 mtu 1500 inet x.x.x.x netmask 255.255.255.255 destination x.x.x.x ppp txqueuelen 3 (Punkt-zu-Punkt-Verbindung) RX packets 10 bytes 202 (202.0 B) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 11 bytes 241 (241.0 B) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 ``` # Requirements Besides a USB Modem with a 1NCE SIM, a Linux Host Device with Command Line Interface access as well as internet access for installing the software is needed. Please insert the 1NCE SIM into the USB Modem according to the manufacturer’s instructions and connect the USB Modem to a free USB port of the Linux system. In this recipe we are using a Raspberry Pi 3 with a Debain-based Linux OS and a Huawei E1550 USB Modem. # Install USB Modem Drivers Dependent on the USB modem, additional drivers might be needed. Please check by searching for the model number of the modem and the used operating system. The connected USB devices can be listed using 'lsusb'. This will show a list, identifying the connected devices. The USB modem needs to be enumerated. In our case, the Huawei modem is correctly listed. # USB Modeswitch This step is not always required! Some USB modems have multiple operating modes that need to be configured. In this case, installing usb-modeswitch can help to switch the device to the correct mode. Please check by searching for the model number of the modem and the used operating system. # Install Wvdial Install the wvdial software using the build in package manager of the Linux OS. # Generate Default Config While the USB modem is connected, run 'sudo wvdial' to create a default configuration file. # 1NCE Config Open the configuration file in a text editor and append the 1NCE wvdial configuration to the file. Please compare the inserted 1NCE configuration to the default values and adapt any differences to the 1NCE setup. Note that the 1NCE setup does not need a username or password. # Initiate Connection The connection to the mobile network can now be started. Please note that this process will take some time to start and is a blocking command. # Terminating Connection The connection can be terminated by using 'ctrl+c'. # Connection Monitoring The connection can be monitored using the 'ifconfig' command. The IP and transmitted data of the point-to-point interface will be listed as a response. # Wrap Up This simple demo should get you started using wvdial on a Linux OS. For further integration of wvdial into custom applications and the operating system specific guides of wvdial. --- # Data Services Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-data-services/
![Schematic overview of the 1NCE data service network structue.](/img/connectivity-services/connectivity-services-data-services/001.png)
The fundamental concept of IoT connectivity refers to millions of devices being connected to the internet and the device capabilities to exchange data packets with other connected services. With a 1NCE SIM, devices can talk to any internet service with a wide variety of data protocols and use this free connectivity to their advantage. Additional features offered by the 1NCE data services provide increased security and usability, but minor limitations for the specific IoT application need to be taken into consideration. In the following sections of this guide, a basic introduction to the features, limitations, terminology, and detailed applications of the data service is provided. For more details about this service, refer to the subchapters in the menu on the left side. As an overview, a good starting point is the [Features & Limitations](/docs/connectivity-services/connectivity-services-data-services/data-services-features-limitations) section to get a better understanding of the possibilities with the 1NCE data service. After mastering these sections, the individual application sections provide an in-depth insight into the setup and implementation of the data service-related features such as [APN Setup](/docs/connectivity-services/connectivity-services-data-services/data-services-apn), [Data Monitoring](/docs/connectivity-services/connectivity-services-data-services/data-services-data-monitoring), and general information about the [Data Volume](/docs/connectivity-services/connectivity-services-data-services/data-services-data-volume). --- # APN Setup Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-data-services/data-services-apn/ An Access Point Name (APN) is defined as the name of the gateway between a mobile network and a core network. The APN specifies to which network and what exact type of network a connection should and can be established. In common mobile networks, the APN defines the name of the gateway which enables the connection towards the open internet. This setting needs to be configured for each device that wants to communicate with an internet service. *** # 1NCE APN Setup > ❗️ APN Setting Required! > > As 1NCE is providing multiple APNs, it is mandatory that a APN is configured. Without a correct APN set, it can not be guaranteed that a device will have a Data Connection. Auto APN configuration is NOT supported. How the APN needs to be configured is dependent on the specific device used with a 1NCE SIM. While most devices only require the APN in URL format, some specific devices require additional parameters to be set. The parameters to set are listed in the table below. Please note that the APN is mandatory to be set and some other parameters are optional or cannot be set manually. | Setting | Value | | :-------------------- | :------------------------------------- | | APN | **iot.1nce.net** | | Username | Not Required, Leave Empty | | Password | Not Required, Leave Empty | | Authentication Method | Password Authentication Protocol (PAP) | | Internet Protocol | Internet Protocol Version 4 (IPv4) | ## 1NCE Access Point Name This parameter needs to be set in the devices with a 1NCE SIM. Please refer to the device manufacturer for a guide on how to set an APN. In most cases, this can be done by a specific AT Command, sending a SMS to the device or via the device user interface. ## Authentication Some devices might require the authentication method setting, username, and password. This authentication procedure can be requested by each side of the connection as part of the establishment process. The two most common authentication procedures are Password Authentication Protocol (PAP) and Challenge Handshake Authentication Protocol (CHAP). PAP is the older protocol and is based on a simple username and password authentication. CHAP is a more sophisticated and more secure authentication method based on randomly generated challenges.\ For the 1NCE APN no username or password is needed. These parameters can be left empty in the configuration. The authentication method PAP should be selected as default if the device requires this parameter. ## Internet Protocol Some devices support both Internet Protocol versions IPv4 and IPv6. The 1NCE core network currently only supports IPv4 for the time being. Therefore, IPv4 must be used. --- # Data Monitoring Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-data-services/data-services-data-monitoring/ When monitoring the data service offered by the 1NCE SIM connectivity, there is more to explore than just tracking the usage volume. Through different means of the 1NCE Portal, [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) and [1NCE API](/api/), the usage volume, data session connection state and device connectivity can be monitored. In the following sections, the capabilities and benefits of each available interface is presented. *** # 1NCE Portal The web portal is a ready-to-use interface for monitoring all 1NCE services. The current status of the data session (PDP context), the overall volume usage, and status messages can be viewed for each SIM. Event records from the data streamer are listed in the web interface. This provides an overview of the state of the 1NCE SIM. The online portal offers a starting point for non-automated monitoring of small batches of SIM or fast debugging of connections. This platform offers no integration possibilities and the logging data is deleted after seven days due to the data retention policy. For more details on how to use the 1NCE Portal, please refer to the [Portal Guide](/docs/1nce-portal/portal-dashboard). *** # Data Streamer The [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) delivers a stream of the event and/or usage records via a wide selection of cloud connectivity applications. The main application case is long-term, automated monitoring of large amount of connected SIM. For the data service, usage volume and event records are part of the stream. Usage records are generated at regular intervals and the end of a data session. The event records show the general connectivity of the device to the mobile network and the creation and deletion of a data session. In the events warnings and errors from the network core are included to ease debugging possibilities. More details are covered in the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) of this guide. *** # 1NCE API The 1NCE API is a powerful tool for querying certain information parameters on demand. An example for the data service is accumulated volume usage records for each SIM card on different time scales. The data usage limits can be requested and set via the API. Furthermore, the current state of the overall available volume and used quota can be queried, and if needed volume top-ups initiated. Please note that certain data will be retained only a fixed amount of time due to the data retention policy. The 1NCE API is ideal for requesting specific information on demand. It is not recommended to use this interface for large, automated queries regularly, please use the data streaming service for this kind of automation. Details about the API can be found in the [API guide](/api/) section of the documentation. --- # Data Volume Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-data-services/data-services-data-volume/ Based on the specific tariff of the 1NCE SIM, a set amount of data volume is included. The used and available volume for each of the SIM can be viewed in the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) or queried through [1NCE API](/api/). The following sections will explain what data volume usage is deducted from the volume and how this can be calculated for some protocols. *** ## Data Volume Usage When using the 1NCE data service, both uplink (UL) and downlink (DL) data transmissions are counted towards the used volume. Taking a look at the different layers in the communication in the figure below, only the traffic inside the GTP is considered for billing. The IP overhead, specific network protocol (e.g., TCP, UDP, MQTT, etc.) overhead, and actual payload size account as data usage. For sending large data packets, IP fragmentation generates further overhead data traffic. It does not matter if the 1NCE VPN service or a direct internet breakout is used as this does not constitute a difference in the usage data.
![Schematic description of the data service layers and their volume usage.](/img/connectivity-services/connectivity-services-data-services/data-services-data-volume/001.png)
Important to note is that besides the overhead for sending a payload, additional data transfers for the connection establishment, synchronize, acknowledge, or retransmission exchanges dependent on the used network protocols need to be accounted for in the data usage. This additional overhead is hard to estimate as it is depended on many other factors (e.g., wireless data link quality, latency, etc.). Example calculations for some of the most commonly used protocols are shown in the [example scenarios](#example-scenarios). *** ## Self-Set Data Volume Limits A customer-specified limit for the data volume can be set in the 1NCE Portal Configuration tab or through the 1NCE API. This limit applies to the usage of data volume for all SIM in the organization. These limits can be used to restrict the data volume usage per month for the SIMs from the network side. The limits can be set in predetermined steps and will be reset on the first day of each new month. ### Reaching and Resetting the Limit If a SIM runs into this limitation, an Event Record **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** will be generated when attempting to create a new data session. Further a customer notification will be generated. To reenable a SIM, please either wait until the volume is reset at the beginning of the month or manually increase the limit via the 1NCE Portal or 1NCE API. > ❗️ Error Warning Exceeded Limit > > When the limit is reached new PDP data sessions will be rejected:\ > **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** > > Please note that some devices might retry indefinitely to reconnect in such a case. 1NCE strongly advices to use a back-off approach in this rejection case to not flood the network with PDP session requests. *** ## Example Scenarios To provide a better understanding of the estimation of data volume usage, a few examples with commonly used network protocols are listed below. ### DNS Resolution When using URLs as a reference, these have to be resolved via a DNS request to obtain the target IP address. This resolution process generates additional traffic which is often overlooked in the usage calculation. The table shown an example data usage for one DNS resolution. Dependent on the IoT device software, multiple DNS queries might be executed as part of a normal operation. > 📘 Avoiding DNS Resolution > > It is possible to avoid the DNS resolution if the IP address of the destination is known. In this case, the device should be configured to send data to the IP instead of the DNS. > > However, this comes with a risk. For example, the application may stop working should the IP change. Usually, the DNS stays the same but point to the correct IP, even when a new IP is being used.\ > As such, there is a risk that at some point of time data is not reaching its intended destination as the IP was reassigned. Therefore, we generally recommend using the address "udp.os.1nce.com" instead of the IP behind the DNS. | Description | DNS/UDP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **DNS Resolution** | **94 Bytes** | **40 Bytes** | **134 Bytes** | | *DNS Query* e.g. [www.google.de](http://www.google.de) | 39 Bytes | 20 Bytes | 59 Bytes | | *DNS Response* | 55 Bytes | 20 Bytes | 75 Bytes | ### Transmission Control Protocol (TCP) In this use case, the minimal TCP network protocol is used to send a payload of 100 bytes of data from a device towards a server. Afterward, 50 bytes are returned from the server towards the device. The shown calculation is based on the assumption that no retransmissions will be needed. Depending on the application and the used header options for TCP and IP, the size of these packets will be larger. | Description | TCP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **3-Way Handshake** | **64 Bytes** | **60 Bytes** | **124 Bytes** | | *SYN* | 20 Bytes | 20 Bytes | 40 Bytes | | *SYN/ACK* | 24 Bytes | 20 Bytes | 44 Bytes | | *SYN* | 20 Bytes | 20 Bytes | 40 Bytes | | **Payload Exchange** | **230 Bytes** | **80 Bytes** | **310 Bytes** | | *PSH/ACK* *100 Bytes Payload* | 120 Bytes | 20 Bytes | 140 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *PSH/ACK* *50 Bytes Payload* | 70 Bytes | 20 Bytes | 90 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | **Connection Shutdown** | **80 Bytes** | **80 Bytes** | **160 Bytes** | | *FIN/ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *FIN/ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | **Total Sum** | **374 Bytes** | **220 Byte** | **594 Bytes** | ### User Datagram Protocol (UDP) In comparison to the TCP header (20 bytes), the UDP header with only 8 bytes is more lightweight. Furthermore, UDP does not rely on the 3-way handshake and acknowledging individual data packets. This makes it a bit more unreliable but can save a lot of transmitted data in suitable applications. The use case shown in the calculation is the same as for the TCP example. A payload of 100 bytes of data from a device towards a UDP server. Afterward, 50 bytes are returned from the server towards the device. | Description | UDP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **Payload Exchange** | **166** | **40** | **206** | | *Device to Server* *100 Bytes Payload* | 108 | 20 | 128 | | *Server to Device* *50 Bytes Payload* | 58 | 20 | 78 | | **Total Sum** | **166** | **40** | **206** | --- # Features & Limitations Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-data-services/data-services-features-limitations/ # Features ## Service Availability The data service is available with all 1NCE SIMs using the Radio Access Technologies (RAT) 2G, 3G, 4G, LTE Cat-M and NB-IoT. The local availability depends on the coverage of the 1NCE roaming partners. Not all RAT are provided in each country. ## Data Bandwidth Throughput While most IoT applications might only have low bandwidth and not very strict latency requirements, other use cases might require high bandwidth with low latency. The 1NCE Data Service offers a maximum guaranteed data throughput of one megabit per second (**1 MBit/s**). Please note that the achievable throughput and latency are dependent on the used RAT, device specifications, and environmental factors (e.g., location, signal reception, etc.). ## SIM - IP Address * Each customer gets personal, private Internet Protocol (IP) ranges assigned for their SIM cards. * 1NCE uses addresses from the private IP space (RFC 1597) which are not allocated in the public internet and thus can be used freely in private networks. * All SIM cards assigned will have an IP address of one or more dedicated IP address spaces. * Usually, /24 address spaces will be used where in total 254 SIM cards can be fitted into. It is possible that /16 IP spaces with 65.536 individual SIM addresses might be used in newer organizations. * Additional IP space(s) will be assigned automatically. * SIMs will be assigned randomly to the IP space(s) of the given organization. * SIM IP address will be static as long as the SIM is not transferred between (sub-)organizations. A transfer will cause a change in IP address. * It is possible that a SIM card can get assigned a x.x.x.0 IP address. * The IP address spaces assigned to your account can be verified in the 1NCE Portal. > 📘 SIM IP Spaces Changes > > Please note that the pool of general SIM IP Spaces might be altered and new spaces might be added later on to increase overall capacity. ## SIM - IP Spaces All 1NCE SIMs are assigned IP Addresses from the following general IP Spaces. The IP Spaces assigned to customers will originate from these larger spaces. It is important to keep track of these spaces especially for VPN, IP Sec and VPN Peering setups. * 100.64.0.0/10 * 10.21.0.0/16 * 10.22.0.0/15 * 10.24.0.0/14 * 10.32.0.0/12 * 10.52.0.0/14 * 10.56.0.0/14 * 10.129.0.0/16 * 10.130.0.0/15 * 10.132.0.0/14 * 10.137.0.0/16 * 10.138.0.0/15 * 10.140.0.0/14 * 10.144.0.0/13 * 10.152.0.0/14 * 10.156.0.0/15 * 10.160.0.0/11 * 10.192.0.0/10 * 10.240.0.0/13 * 10.248.0.0/13 ## Network Translation and 1NCE VPN The infrastructure of the 1NCE Data Service network uses Network Address Translation (NAT) to route traffic from each connected SIM device to the public internet. For providing a private, more secure connectivity, as the devices are not directly exposed to the public internet. This also implies that a connection establishment from an application on the internet towards a 1NCE SIM is not directly possible without using the 1NCE VPN Service. On the other hand, target locations in the public internet space can be reached from any device with a 1NCE SIM. The traffic from each device is routed via the 1NCE Internet Breakout. For more details review the 1NCE Network Services, [Internet Breakout](/docs/network-services/network-services-internet-breakout) and [VPN Service](/docs/network-services/network-services-vpn-service/). > 📘 Data Connection Establishment > > When using the default Internet Breakout, the SIM device has to establish the Data Connection towards the targeted internet service. Due to the NAT Gateway, individual SIMs are not reachable from the open internet. The sequence diagram below shows the flow of a SIM device using the NAT Internet Breakout to establish a connection to a public internet server/service. The connection establishment always needs to come from the SIM device. After a connection session (e.g., TCP session) was opened by the SIM device, bidirectional communication is possible.
![Schematic sequence diagram of a data session establishment.](/img/connectivity-services/connectivity-services-data-services/data-services-features-limitations/001.png)
The second sequence diagram below shows the possible data service when using the 1NCE VPN Service. This free to use service allows to directly connect to the 1NCE Network to access/connect SIM devices from the customer server side. Please note that only traffic from the SIM device with the VPN client IP address as destination will be routed towards the connected VPN client. All other traffic from the SIM device will be routed through the Internet Breakout. For more details, please see the VPN Service chapter.
![Schematic sequence diagram of a data session establishment using the 1NCE VPN service.](/img/connectivity-services/connectivity-services-data-services/data-services-features-limitations/002.png)
## Data Protocols The concept of the Open Systems Interconnection model applies to the 1NCE Data Service structure. The GPRS Tunneling Protocol (GTP) is used on layer 3 to transfer user application data between the device with a 1NCE SIM and the internet or application server and vice versa. All the data traffic is wrapped in the GTP, on top of this protocol (layer 4+) the customer is free to use any transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port assignment. ## Domain Name System (DNS) The Domain Name System (DNS) is used to resolve Uniform Resource Locators (URL) to an addressable IP. When using the 1NCE Internet Breakout, the public IP `8.8.8.8` is served as primary and `8.8.4.4` as secondary default Domain Name Server. Some devices have issues with obtaining the DNS served by the network. A manual configuration of a DNS is sometimes advisable. On some NB-IoT U-Blox devices used in Europe, MNO profile 101 has to be used rather than MNO profile 100 to obtain the DNS served by the network. *** # Limitations ## Maximum Transmission Unit (MTU) Size The Maximum Transmission Unit (MTU) is the size of the largest IP packet (layer 4) possible which can be transferred in a respective frame on layer 3 without the need for fragmentation in the packed based core network. If a send packet is larger than the specified MTU, the packet needs to be fragmented, thus creating more overhead and delays. Theoretically, a size of 1500 bytes is possible with the 1NCE Data Service. Based on prior experience with IoT devices and mobile networks, it is recommended to keep the **MTU size lower than about 1200 bytes**. ## Data Volume Usage Based on the customer specific tariff of a 1NCE SIM, a certain data volume is included. The available volume and current usage can be inquired in the 1NCE Portal or through the [1NCE API](/api/). The data volume can be used freely. If the volume runs out or customer-set threshold is reached, the Data Service for a SIM card is blocked. No new data sessions (PDP Context) can be initialized. The device can still attach to the mobile network and use the other services but is not able to re-create a new PDP Context. Moreover, any existing data session is terminated if the volume limit is reached. If the restricted SIM is topped up with new data volume, the blocking will be reset and new data sessions can be established. If a SIM runs out of data volume, the device **should restrict the attempts to create new (failed) PDP sessions** as the reject response can lead to the device spamming the network with session requests. Please note that the customer is responsible for implementing a back off timer for this edge case behavior. {/* ## Internet Breakout Timeout > ❗️ > > **This does only apply to connections made through the 1NCE Internet Breakout and NOT the 1NCE VPN Service!** Devices using the 1NCE Internet Breakout are placed behind a NAT gateway. After 350 seconds of no packets being transmitted, a established connection via the 1NCE Internet Breakout will be closed automatically. To keep the connection alive within 350 seconds a IoT device must send a keep-alive packet at least once in the 350-second timeframe. Otherwise, the 1NCE SIM device must re-establish the connection after this timeout. */} ## 1NCE Breakout IP Blacklisting The traffic from all 1NCE SIMs towards the public internet is routed through a NAT with a couple of public-facing IP addresses. These public breakout IPs are listed in the 1NCE Portal. All requests towards public internet services appear to come from only these few IPS. Most public services and APIs apply a request limit and smart filtering to detect and filter out denial of service (DDoS) and similar attacks. Very frequent queries (e.g., every second) from multiple SIMs towards one endpoint could trigger these filtering mechanisms. This will result in the public service blocking requests from 1NCE SIM devices, rendering the service unusable. Most public services cannot differentiate between individual SIMs due to the 1NCE NAT network structure. It is strongly recommended to program devices with 1NCE SIMs in a way that they do not aggressively query such shared resources. ## Multiple PDP Data Sessions With the 1NCE SIM connectivity, currently only one PDP data session at a time is supported. If the IoT device allows to establish multiple PDP sessions, only the last opened data session can be used to transfer data. Sessions opened prior will remain open but will be dropped on the Packet Gateway. This results in no data being transferred other the older PDP sessions.\ For ease of use ensure to use only one PDP data session at a time and to always properly close each session. ## Device to Device Communication The peer to peer communication between two or multiple SIMs is not possible. This rules is the same for SIMs of one customer or between different customers. There is no direct routing of IP traffic between SIMs possible. To exchange specific data packages between SIM devices, an application server is needed. This application server is ideally connected via the 1NCE VPN Service. Thus, it can receive data messages from one SIM device via the VPN client IP and redirect them to another SIM device in the same customer account by its static IP address. ## TCP/TLS with NB-IoT NB-IoT is great for getting coverage in hard-to-reach areas like basements or countryside. It comes with the disadvantage of higher transmission latency as the radio device repeats transmissions multiple times to allow the receiving cell tower to capture the data accurately. In total, it can add up to an expected latency between 1 and 10 seconds. Compared to the latency of normal LTE or CAT-M of 10 to 100 milliseconds, NB-IoT latency is very high. Due to the high latency, it is not advised to use TCP based protocols for data transmission. These protocols expect lower latency. TCP based protocols can work over NB-IoT in ideal conditions but if the latency increases due to environment changes or radio changes, TCP will start sending retransmissions and the connectivity will start to break. 1NCE recommends using only UDP based protocols like CoAP or LwM2M for NB-IoT radio access type. The feature set of these specialized protocols closely match TCP behavior with the added benefit of being more robust in high latency transmissions. Please avoid using TCP based protocols on NB-IoT radio interfaces. {/* ## PDP Data Session Retention7 days1kb of dataotherwise dropped */} --- # Mobile Network Services Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-mobile-network-services/
![Schematic overview of the 1NCE network structure.](/img/connectivity-services/connectivity-services-mobile-network-services/001.png)
1NCE is not just another Internet of Things (IoT) Mobile Virtual Network Operator (MVNO). In a unique way, 1NCE enhances the capabilities of a full MVNO with the power and quality of Tier-1 mobile networks. Our network capabilities exceed those of traditional MVNOs because we have a direct interface to Radio Access Networks of Tier-1 operators which enable us to control and manage the IoT traffic directly and more eminently. Additionally, we utilize essential network assets of our Mobile Network Operator (MNO) roaming partners to guarantee long-term stability and security of our network services to customers. The Network of 1NCE comprises of both a lean virtualized and a cloud based core network as well as a streamlined and full-automatized business support system. All included network elements as well as the feature set of the platform have been developed with a clear focus on IoT. All functions and features are fully automatized for maximum scale and ease of use. The Mobile Network Services chapters focus on all features and parts around the general mobile network connectivity. --- # 1NCE IoT Network Coverage Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-coverage/
![world_coverage_en_03-2022.png](/img/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-coverage/48a9e97-world_coverage_en_03-2022.png)
The country and region coverage of 1NCE is growing steadily and rapidly. 1NCE already offers radio services through roaming partners in over 100 countries and regions in Europe (including UK), Asia, North America, South America, Africa and Oceania. The 1NCE IoT SIM card can be used in these regions without additional costs. 1NCE supports all radio standards such as 2G, 3G, 4G/LTE-M as well as NB-IoT in selected countries and regions. 1NCE strives to continuously enhance the outreach and coverage of the IoT network. If there is a specific need for a radio access technology in a particular area, please check the Coverage Map to see if the actual service is available or reach out to the 1NCE Support. # GSMA Coverage Estimation Map The GSM Association (GSMA) provides Network Coverage Maps which show the theoretical coverage of mobile network operators for the different radio access technologies. Important to note is that their maps are calculated and are only a rough estimation. The shown values can deviate from the real coverage quite a bit. For 4G/LTE and especially for the optimized RAT LTE Cat M and NB-IoT, the shown coverage is often depicted worse than it actually is.\ Please note that the GSMA maps are a general coverage tool and do not reflect list complete list of the 1NCE Coverage Map. --- # 2G/3G Discontinuation Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-discontinuation/ From the physical side, the radio frequency spectrum used for wireless communication is a very sparse, limited but valuable resource. Each country/region through the world uses and optimizes this common spectrum differently, but the same physical limitations apply.\ As new, more advanced, and powerful mobile radio network technologies emerge, older standards make way for future deployments. Current mobile Radio Access Technologies (RAT) range from 2G (GSM), 3G (UMTS), 4G (LTE) including NB-IoT and LTE Cat-M to the most recent fifth generation 5G. The advancements in 4G and 5G provide simpler, scalable network structures and are more optimized for IoT and future-driven use cases compared to 2G and 3G. As a result, many Mobile Network Operators (MNO) decided to discontinue 2G and/or 3G to make space in the radio frequency bands for 4G and 5G deployments. # Migrating to Future-Proof Technologies Early on mobile IoT device integrations used 2G/3G RATs as primary network resource. Today, many deployed IoT devices still use older RATs as fallback solution as new radio standards (e.g., NB-IoT and LTE-M/Cat-M) start to be deployed. This is backed by the usage statistics we see in the 1NCE Network. While in the European Region 2G still is the dominating standard for IoT applications, the adaption and demand for 4G/LTE with NB-IoT and LTE Cat-M is increasing significantly as availably of affordable modem hardware and international network coverage grows. As most IoT device integrations aim for long-term deployment, device developers and manufactures need to be on the lookout for ongoing radio resource reallocations in mobile networks. It is all about choosing the right radio technology for future usage. From the SIM card perspective, the 1NCE SIM cards support all Radio Access Technologies (2G, 3G, 4G, Cat-M and NB-IoT). To future-prove IoT hardware devices, 1NCE recommends the usage of 4G and the related LTE Cat-M and NB-IoT modem hardware wherever it is possible. 2G and 3G are good alternatives to use for providing a fallback in case of a 4G outage but should ideally not be considered main point of future IoT connectivity. # Upcoming 2G (GSM) & 3G (UMTS) Discontinuations Different countries and regions follow different shutdown/sunset/discontinuation patterns when it comes to mobile radio networks. In European Region, mostly 3G (UMTS) services are shut down and 2G (GSM) radio coverage is preserved due to fallback and emergency service use cases. In the US, Asia and Australia, the focus on freeing up radio resources lies on 2G (GSM) network resources. As 1NCE IoT SIM connectivity relies on their roaming partners for local radio coverage, the overall coverage and available Radio Access Technologies are impacted by the local shutdowns. The list below provides an overview of upcoming changes due to discontinuations in the 1NCE Coverage. | Country/Region | Network Operator | Also known as | 2G (GSM) | 3G (UMTS) | | :--- | :--- | :--- | :--- | :--- | | Albania | Vodafone Albania | \- | \- | Completed | | Andorra | Andorra Telecom S.A.U. | \- | \- | 01.09.2026 | | Anguilla | Cable & Wireless (West Indies) Ltd. Anguilla (Flow) | \- | Completed | \- | | Anguilla | Digicel (Jamaica) Limited | \- | Completed | \- | | Antigua & Barbuda | Cable & Wireless (Anguilla) Limited | \- | Completed | \- | | Antigua & Barbuda | Digicel (Jamaica) Limited | \- | Completed | \- | | Argentina | Telenet Group BVBA/SPRL | \- | \- | Completed | | Aruba | Digicel (Jamaica) Limited | \- | Completed | \- | | Aruba | SETAR (Servicio di Telecomunicacion di Aruba) | \- | 01.08.2026 | \- | | Australia | Optus Mobile Pty Ltd | \- | Completed | \- | | Australia | Telstra Cooperation Ltd | \- | Completed | \- | | Austria | A1 Telekom Austria AG | \- | 31.05.2028 | Completed | | Austria | Hutchison 3 Austria GmbH | \- | \- | Completed | | Bahrain | STC Bahrain B.S.C Closed | \- | \- | Completed | | Bahrain | Zain Bahrain B.S.C | \- | \- | Completed | | Bangladesh | Grammenphone Ltd. | \- | \- | Completed | | Barbados | Cable & Wireless Barbados Ltd. | \- | Completed | \- | | Barbados | Digicel (Jamaica) Limited | \- | Completed | \- | | Belgium | Orange Belgium NV/SA | \- | 31.12.2028 | Completed | | Belgium | Telenet Group BVBA/SPRL | \- | 31.12.2027 | Completed | | Bermuda | Digicel (Jamaica) Limited | \- | Completed | \- | | Bonaire (Netherlands Antilles) | Curacao Telecom N.V. | \- | 30.11.2026 | 31.03.2028 | | British Virgin Islands | Cable & Wireless West Indies | \- | Completed | \- | | British Virgin Islands | Digicel (Jamaica) Limited | \- | Completed | \- | | Bulgaria | A1 Bulgaria | \- | \- | Completed | | Canada | Bell Mobility Inc. | \- | \- | 01.03.2027 | | Canada | SaskTel | \- | Completed | 01.10.2027 | | Canada | TELUS Communications Canada Inc. | \- | Completed | \- | | Cayman | Cable & Wireless West Indies | \- | Completed | \- | | Cayman | Digicel (Jamaica) Limited | \- | Completed | \- | | China | China Mobile International Limited | \- | 23.06.2026 | Completed | | China | China Unicom | \- | Completed | 30.06.2026 | | Colombia | Colombia Movil S.A. | \- | Completed | \- | | Colombia | Comunicacion Celular S.A. (Claro) | \- | Completed | \- | | Costa Rica | I.C.E. (Instituto Costarricense de Electricidad) | \- | Completed | \- | | Costa Rica | LIBERTY TELECOMUNICACIONES DE COSTA RICA LY | \- | Completed | \- | | Croatia | A1 Hrvatska d.o.o. | \- | \- | Completed | | Croatia | Croatian Telecom Inc. | \- | \- | Completed | | Curacao (Netherlands Antilles) | Curacao Telecom N.V. | \- | 30.11.2026 | 31.03.2028 | | Cyprus | Cyprus Telecommunications Authority (Cyta) | \- | \- | 31.12.2027 | | Czech Republic | O2 Czech Republic, a.s. | \- | \- | Completed | | Czech Republic | T-Mobile Czech Republic | \- | 01.01.2028 | Completed | | Czech Republic | Vodafone Czech Republic | \- | Completed | Completed | | Denmark | Hi3G Denmark ApS | \- | \- | Completed | | Denmark | TDC NetCo | \- | \- | Completed | | Denmark | Telenor A/S | \- | \- | Completed | | Denmark | Telia Denmark ApS | \- | \- | Completed | | Dominica | Cable & Wireless Dominica Ltd. | \- | 30.08.2026 | \- | | Dominica | Digicel (Jamaica) Limited | \- | Completed | \- | | El Salvador | Telemovil EL Salvador S.A | \- | Completed | \- | | Estonia | Elisa Eesti AS | \- | 31.12.2029 | \- | | Estonia | Tele2 Eesti AS | \- | \- | Completed | | Estonia | Telia Eesti | \- | 31.12.2029 | \- | | Finland | Alands Telekommunikation Ab | \- | Completed | \- | | Finland | DNA Ltd | \- | 31.12.2029 | \- | | Finland | Elisa Corporation | \- | \- | Completed | | Finland | Telia Finland Oyj | \- | \- | Completed | | France | Bouygues Telecom France | \- | 31.12.2026 | 31.12.2029 | | France | Orange France | \- | 31.12.2026 | 31.12.2028 | | France | SFR France | \- | 31.12.2026 | 31.12.2028 | | French Guiana | Digicel Antilles Française | \- | Completed | \- | | French Guiana | Orange Caraibe | \- | Completed | 31.12.2028 | | Germany | Deutsche Telekom | \- | 30.06.2028 | Completed | | Germany | O2 / Telefónica Germany GmbH & Co. OHG | \- | \- | Completed | | Germany | O2 / Telefónica Germany GmbH & Co. OHG | \- | \- | Completed | | Germany | Vodafone | \- | 31.12.2030 | 31.12.2030 | | Great Britain | EE | \- | \- | Completed | | Great Britain | EE Limited | \- | \- | Completed | | Great Britain | Hutchison 3G UK Ltd | \- | \- | Completed | | Great Britain | O2/Telefonica UK Limited | \- | Start summer 2029 | Completed | | Great Britain | Vodafone UK Limited | \- | 31.12.2030 | Completed | | Greece | COSMOTE Mobile Telecommunications S.A | \- | \- | Completed | | Greece | Vodafone Roaming Services S.A.R.L. | \- | \- | Completed | | Greece | WIND HELLAS Telecommunications S.A | \- | \- | Completed | | Greenland | Tele Greenland A/S | \- | \- | Completed | | Grenada | Cable & Wireless Grenada Ltd. | \- | Completed | \- | | Grenada | Digicel (Jamaica) Limited | \- | Completed | \- | | Guadeloupe (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Guadeloupe (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Guam | PTI Pacifica Inc. dba IT&E | \- | \- | Completed | | Guernsey | JT (Jersey) Limited | \- | \- | Completed | | Haiti | Digicel (Jamaica) Limited | \- | Completed | \- | | Hong Kong | Hong Kong Telecommunications (HKT/CSL) Limited (PCCW) | \- | Completed | \- | | Hong Kong | Hutchison Telecommunications Hong Kong Holdings Limited | \- | Completed | 31.10.2026 | | Hong Kong | SmarTone | \- | Completed | 30.09.2026 | | Hungary | Magyar Telekom Plc. | \- | \- | Completed | | Hungary | Yettel Magyarország | \- | \- | Completed | | Iceland | Nova Island | \- | \- | Completed | | Iceland | Síminn hf | \- | Completed | Completed | | Iceland | Sýn hf. (Vodafone) | \- | Completed | \- | | India | Airtel Andhra Pradesh | \- | \- | Completed | | India | Airtel Assam | \- | \- | Completed | | India | Airtel Bihar | \- | \- | Completed | | India | Airtel Chennai | \- | \- | Completed | | India | Airtel Delhi | \- | \- | Completed | | India | Airtel Gujarat | \- | \- | Completed | | India | Airtel Haryana | \- | \- | Completed | | India | Airtel Himachal Pradesh | \- | \- | Completed | | India | Airtel Karnataka | \- | \- | Completed | | India | Airtel Kerala | \- | \- | Completed | | India | Airtel Kolkata | \- | \- | Completed | | India | Airtel Madhya Pradesh | \- | \- | Completed | | India | Airtel Maharashtra & Goa | \- | \- | Completed | | India | Airtel Mumbai | \- | \- | Completed | | India | Airtel North East | \- | \- | Completed | | India | Airtel Orissa | \- | \- | Completed | | India | Airtel Punjab | \- | \- | Completed | | India | Airtel Rajasthan | \- | \- | Completed | | India | Airtel Tamilnadu | \- | \- | Completed | | India | Airtel UP East | \- | \- | Completed | | India | Airtel Uttar Pradesh West | \- | \- | Completed | | India | Airtel West Bengal | \- | \- | Completed | | Indonesia | PT Indosat Tbk (Indosat Ooredoo) | \- | \- | Completed | | Indonesia | PT. XL Axiata Tbk | \- | \- | Completed | | Israel | Hot Mobile Ltd. | \- | Completed | Completed | | Israel | Partner Communications Company Ltd. | \- | Completed | Completed | | Israel | Pelephone Communications Ltd. | \- | Completed | Completed | | Italy | Telecom Italia SpA | \- | 31.12.2029 | Completed | | Italy | Vodafone Italy | \- | \- | Completed | | Italy | Wind Tre S.p.A. | \- | \- | Completed | | Jamaica | Cable & Wireless Jamaica Limited | \- | Completed | \- | | Jamaica | Digicel (Jamaica) Limited | \- | Completed | \- | | Japan | KDDI | \- | Completed | Completed | | Japan | NTT DoCoMo | \- | Completed | Completed | | Japan | Softbank KK | \- | Completed | \- | | Jersey | JT (Jersey) Limited | \- | \- | Completed | | Jordan | Umniah Mobile Company | \- | Completed | \- | | Korea, Republic of | KT Corporation | \- | Completed | \- | | Korea, Republic of | LG Uplus Corporation | \- | Completed | \- | | Korea, Republic of | SK Telecom | \- | Completed | \- | | Kosovo | IPKO Telecommunications LLC | \- | \- | Completed | | Kuwait | National Mobile Telecommunications Company (K.S.C) | \- | \- | Completed | | La Désirade (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Latvia | Latvijas Mobilais Telefons SIA | \- | \- | Completed | | Latvia | SIA Bite Mobile | \- | \- | Completed | | Latvia | TELE2 Latvia | \- | \- | Completed | | Les Saintes (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Liechtenstein | Telecom Liechtenstein AG | \- | Completed | Completed | | Lithuania | Telia Lietuva, AB | \- | 31.12.2028 | Completed | | Lithuania | UAB Bite Lietuva | \- | 31.12.2028 | Completed | | Luxembourg | Orange Luxembourg | \- | 31.12.2030 | Completed | | Luxembourg | Post Luxembourg | \- | 31.12.2026 | Completed | | Luxembourg | Tango SA | \- | \- | Completed | | Macau | Companhia de Telecomunicações de Macau, S.A.R.L. | \- | Completed | Completed | | Macedonia, North | Makedonski Telekom AD Skopje | \- | \- | Completed | | Malaysia | Digi Telecommunications Sdn Bhd | \- | \- | Completed | | Malaysia | Maxis Broadband Sdn. Bhd. | \- | \- | Completed | | Mariana Islands | PTI Pacifica Inc. dba IT&E | \- | \- | Completed | | Marie Galante (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Marie Galante (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Martinique (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Martinique (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Mayotte | Orange Reunion | \- | Completed | \- | | Mexico | AT&T Comercialization Mexico | \- | Completed | \- | | Montenegro | CRNOGORSKI TELEKOM A.D. | \- | \- | Completed | | Montenegro | MTEL d.o.o. Podgorica | \- | Completed | \- | | Montserrat | Digicel (Jamaica) Limited | \- | Completed | \- | | Nepal | Ncell Axiata Limited | \- | \- | From July 2026 | | Nepal | Nepal Doorsanchar Company | \- | Completed | \- | | Netherlands | KPN B.V. | \- | 01.12.2027 | Completed | | Netherlands | T-Mobile Netherlands | \- | Completed | \- | | Netherlands | Vodafone Libertel N.V. | \- | 31.12.2026 | Completed | | New Caledonia | Office des Postes et Telecommunications | \- | Completed | \- | | New Zealand | Spark New Zealand Trading Limited | \- | Completed | Completed | | New Zealand | Two Degrees Networks Limited | \- | Completed | Completed | | Norway | Telenor Norge AS | \- | 31.12.2027 | Completed | | Norway | Telia Norge AS | \- | Completed | Completed | | Oman, Sultanate of | Oman Telecommunications Company S.A.O.G. | \- | \- | Completed | | Oman, Sultanate of | Omani Qatari Telecommunications Company | \- | \- | Completed | | Philippines | Smart Communications, Inc. | \- | \- | 31.12.2026 | | Poland | Orange Polska S.A. | \- | 31.12.2030 | Completed | | Poland | T-Mobile Polska S.A. | \- | 31.12.2030 | Completed | | Puerto Rico | AT&T USA | \- | Completed | \- | | Puerto Rico | T-Mobile USA | \- | \- | Completed | | Qatar | Ooredoo QSC | \- | \- | Completed | | Qatar | Vodafone | \- | \- | Completed | | Reunion | Orange Reunion | \- | Completed | \- | | Romania | Orange Romania | \- | 31.12.2030 | Completed | | Romania | Telekom Romania Mobile Communications S.A. | \- | \- | Completed | | Romania | Vodafone Romania S.A. | \- | Completed | \- | | Saint Barthelemy | Digicel Antilles Française | \- | Completed | \- | | Saint Barthelemy | Orange Caraibe | \- | Completed | 31.12.2028 | | Saint Kitts & Nevis | Digicel (Jamaica) Limited | \- | Completed | \- | | Saint Lucia | Digicel (Jamaica) Limited | \- | Completed | \- | | Saint Martin (French part) | Digicel Antilles Française | \- | Completed | \- | | Saint Martin (French part) | Orange Caraibe | \- | Completed | 31.12.2028 | | Saint Vincent and Grenadines | Digicel (Jamaica) Limited | \- | Completed | \- | | Saudi Arabia | Saudi Telecom Company (STC) | \- | \- | Completed | | Serbia | A1 Serbia | VIP Mobile | \- | Completed | | Singapore | SIMBA | \- | Completed | \- | | Singapore | SingTel Mobile | \- | Completed | Completed | | Singapore | StarHub Mobile Pte Ltd | \- | Completed | Completed | | Sint Maarten (Netherlands Antilles) | Telcell N.V. | \- | Completed | \- | | Slovak Republic | O2 Slovakia, s.r.o. | \- | \- | Completed | | Slovak Republic | Orange Slovensko A.S | \- | 31.12.2030 | Completed | | Slovak Republic | Slovak Telekom, a.s. | \- | \- | Completed | | Slovenia | A1 Slovenija d.d. | \- | 31.12.2030 | Completed | | Slovenia | Telekom Slovenije d.d. | \- | \- | Completed | | South Africa | MTN South Africa | \- | 31.12.2027 | 31.12.2027 | | South Africa | Telkom South Africa | \- | 31.12.2027 | 31.12.2027 | | South Africa | Vodacom South Africa | \- | 31.12.2027 | 31.12.2027 | | Spain | Orange Espagne S.A.U. | \- | 31.12.2030 | 31.12.2027 | | Sri Lanka | Dialog Axiata PLC | \- | \- | Completed | | Sri Lanka | Mobitel (Pvt) Limited | \- | \- | Completed | | Suriname | Digicel Suriname N.V. | \- | Completed | 31.03.2029 | | Sweden | Hi3G Access AB | \- | \- | Completed | | Sweden | Tele2 AB Sweden | \- | Completed | Completed | | Sweden | Telenor Sverige AB | \- | Completed | Completed | | Sweden | Telia Sverige AB | \- | 31.12.2027 | Completed | | Switzerland | Salt Mobile SA (formerly Orange) | \- | Completed | \- | | Switzerland | Sunrise, Switzerland | \- | Completed | Completed | | Switzerland | Swisscom Mobile Ltd. | \- | Completed | Completed | | Taiwan | Chungwa Telecom LDM Taiwan | \- | Completed | Completed | | Taiwan | Far Eastone Taiwan | \- | Completed | Completed | | Taiwan | Taiwan Mobile Co., Ltd. | \- | Completed | Completed | | Taiwan | Taiwan Star Telecom Corporation Limited | \- | Completed | Completed | | Tanzania | Viettel Tanzania Limited | \- | 30.09.2026 | Completed | | Thailand | Advanced Wireless Network Company (AIS) | \- | 30.09.2026 | 30.09.2026 | | Thailand | True Move Company Ltd. | \- | Completed | \- | | Thailand | True Move H Universal Communication | \- | Completed | \- | | Trinidad and Tobago | Digicel Trinidad and Tobago Ltd | \- | Completed | 31.03.2029 | | Tunisia | Ooredoo Tunisie SA | \- | \- | 30.06.2026 | | Tunisia | Orange Tunisie, SA | \- | \- | 30.06.2026 | | Tunisia | Tunisie Telecom | \- | \- | 30.06.2026 | | US Virgin Islands | AT&T USA | \- | Completed | \- | | US Virgin Islands | T-Mobile USA | \- | \- | Completed | | USA | AT&T USA | \- | Completed | \- | | USA | Cellular One (Smith Bagley, Inc.) | \- | Completed | Completed | | USA | NE Colorado Cellular, Inc | \- | Completed | \- | | USA | T-Mobile USA | \- | \- | Completed | | USA | Union Telephone Company | \- | \- | Completed | | Ukraine | Kyivstar JSC | \- | \- | 31.12.2030 | | Ukraine | Lifecell LLC | \- | \- | 31.12.2030 | | Ukraine | Vodafone | \- | \- | 31.12.2030 | | United Arab Emirates | DU | \- | Completed | \- | | Venezuela | Corporacion Digitel C.A. | \- | Completed | \- | | Venezuela | Digitel Venezuela | \- | Completed | \- | | Vietnam | MobiFone Corporation | \- | 30.09.2026 | 30.09.2028 | | Vietnam | VNPT International | \- | 30.09.2026 | 30.09.2028 | | Vietnam | Viettel Group | \- | 30.09.2026 | Completed | Table Version 01.07.2026 Please review the 1NCE Coverage Map to get an up-to-date view of the available country and access technology coverage. --- # No Harm to Network Guidelines Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-no-harm-network/ To ensure reliable availability of all devices connected in the Internet of Things, network providers put in a lot of technological and human effort around the clock. But IoT developers can also contribute a lot to the efficiency and reliability of their IoT devices and platforms. We have compiled the top 5 for secure and long-term operation of IoT devices in the Internet of Things: ## 1. Avoid Synchronized Behavior IoT devices should never contact their platform at the same time to avoid congestion. ## 2. Reduce Connection Setup Avoid unnecessary connection setup and disconnection of devices. This saves energy and reduces the load on servers and networks. ## 3. Aggregate, Compress, Encode Data If you transfer your data in an optimized way, you extend the battery life of your devices. ## 4. Suitable Energy-Saving Modes Depending on the application, energy can be saved in different ways at the network and application level. ## 5. Always Diagnose Before Restarting Always identify errors before restarting devices. *** This IoT Solution Guideline summarizes the "No Harm to Network" requirements from 1NCE GmbH originating in GSMA TS.34 v5.0, IoT Device Connection Efficiency Guidelines 1, use-cases or features not covered yet within GSMA TS.34, as well as lessons learned gained from IoT commercial deployments. The requirements including the words **"SHALL"** or **"SHALL NOT"** in their descriptions are mandatory and all guidelines with **"SHOULD"** or **"SHOULD NOT"** are recommended. These guidelines are divided into three sections, reflecting how IoT Service Providers are required to implement "No Harm to Network" considerations and best-practice design in the different IoT Solution Layers (refer to Figure 1).
![iot_guidelines.jpg](/img/connectivity-services/connectivity-services-no-harm-network/956b1b9-iot_guidelines.jpg)
*** # Definitions ## IoT Service Provider Companies offering IoT Services to end consumers or enterprises via the 1NCE GmbH Connectivity Layer (3GPPTM mobile networks). ## IoT Service Application Business application logic of the IoT Service which processes the data collected from assets. The IoT Service Provider hosts their IoT Service Application on a server or Cloud Platform provided by 1NCE GmbH or another third party. ## Cloud Platform Infrastructure used by the IoT Service Provider to host IoT Services, manage IoT Devices and exchange data with their IoT Devices over the 1NCE GmbH Connectivity Layer. The Cloud Platform may host the IoT Server Application logic and includes Service Enablement functions. Generally, this is referred to as the "IoT Service Platform" in this document. ## Service Enablement Core service functions such as device management, discovery, registration, group management, application and service management, communication management, data management, service charging and accounting, as well as subscription and notification, are common needs across the wide spectrum of IoT solutions. These aspects are typically coordinated between IoT Devices and the IoT Service Platform on this logical layer. Server-side, service enablement may be handled by an independent orchestrator or connector acting as an endpoint for all communication to/from the IoT Devices. Such a connector may be placed in front of one or several clouds hosting IoT Server Applications. The provider of the Service Enablement may be a Mobile (Virtual) Network Operator, or the developer of the IoT Device and Server Applications. ## IoT Device Sensors, actuators, or other deployed Machine to Machine (M2M) hardware exchanging data bidirectionally and managed by the IoT Service Provider over the Application, Service Enablement and Connectivity Layers. The communication between IoT Device and IoT Service Provider is referred to as the IoT Service. ## IoT Device Application The application logic running on the IoT Device microcontroller (MCU) and exchanging data with the IoT Service Platform. It sends AT commands to the IoT Device integrated communication module/chipset in order to access the 1NCE GmbH Connectivity Layer. *** # IoT Service Provider Guidelines ## Avoidance of Synchronized Behavior Any IoT Service Platform or IoT Service Application which communicates to multiple IoT Devices **SHALL** avoid timely synchronized behavior and employ a randomized pattern for accessing IoT Devices registered to the platforms domain. The triggering of data transmissions, the rebooting of the IoT Device hardware or subcomponents (such as the communication module/chipset), or the issuing device management commands (including, but not limited to (re-) registrations and firmware updates) **SHALL NOT** be timely synchronized. ## IoT Service Platform or IoT Service Application Temporarily Offline Recovery If the IoT Service Platform or IoT Service Application are temporarily offline, they **SHALL NOT** request the IoT Devices to synchronize all at once when coming back online. ## Triggering Devices only when Attached The IoT Service Platform or IoT Service Application **SHALL** be aware of the IoT Device state and only send "wake up" triggers whenever the IoT Device is known to be attached to the mobile network. ## Behavior when IoT Device does not Respond to SMS Triggers If the IoT Service Platform or IoT Service Application uses SMS triggers to "wake up" IoT Devices, it **SHALL** avoid sending multiple SMS triggers when no response is received within a certain time period. Communication over a 3GPPTM NB-IoT access bearer **SHALL NOT** use SMS on 1NCE GmbH mobile network. ## Behavior when SIM Subscription is Inactive If the SIM subscription associated with an IoT Device is to be placed in a temporarily inactive state (i.e. for a fixed period of time), the IoT Service Provider **SHALL** first ensure that the IoT Device’s communication module/chipset is temporarily disabled to restrict it from trying to register to the mobile network once the SIM is disabled. ## Behavior when SIM Subscription is Permanently Disabled Before the SIM subscription associated with an IoT Device is to be placed in a permanently terminated state, the IoT Service Provider **SHALL** first ensure that the IoT Device’s communication module/chipset is permanently disabled to restrict it from trying to register to the mobile network once the SIM is disabled. The IoT Service Provider **SHOULD** consider avoiding mechanisms for the permanent termination of IoT Devices that are not easily serviceable, as it may require manual intervention (i.e. a service call) to reenable the IoT Devices. ## Frequency and Prioritization of Data Transmissions Whenever there is a need to transmit data over the mobile network, the IoT Service Platform or IoT Service Application **SHOULD classify** the priority of each communication. The IoT Service Platform or IoT Service Application distinguishes between high-priority data requiring instantaneous transmission, versus delay tolerant or lower-priority data which can be aggregated and sent during non-peak hours.\ IoT Server Applications communicating with IoT Devices over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, SHALL optimize their application reporting period to never exceed 1NCE GmbH affiliate tariff daily maximum number of messages. ## Data Aggregation, Compression and Transcoding The IoT Server Application **SHALL** minimize the number of parallel mobile network connections and overall frequency of connections to IoT Devices over the mobile network. Data is aggregated by the IoT Server Application into an application report before being compressed and sent over the mobile network. Data transcoding and compression techniques are used, as per the IoT Service’s intended Quality of Service, to reduce connection attempts and data volumes.\ IoT Server Application using 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, SHALL optimize their payload sizes to comply with 1NCE GmbH affiliate monthly volume limits.\ IoT Service Provers SHALL NOT initialize significant numbers of IoT Devices (e.g. >100 units) communicating over 3GPPTM NB-IoT within one hour at the same location. *** # IoT Device Guidelines ## Avoidance of Synchronized Behavior The monolithic IoT Device Application **SHALL** avoid synchronized behavior with other IoT Devices or events, employing a randomized pattern (e.g. over a time period ranging from a few seconds to several hours, or days) to request a mobile network connection over the Connectivity Layer. The triggering of data transmissions, the rebooting of the IoT Device hardware or subcomponents (such as the communication module/chipset), or execution of device management commands (including, but not limited to (re-) registrations and firmware updates) **SHALL NOT** be synchronized. ## Use of "Always-On" Connectivity If the monolithic IoT Device Application sends data very frequently (i.e. inactivity periods shorter than two hours), it **SHALL** use a persistent PDP/PDN connection with the mobile network instead of activating and deactivating said connectivity. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. ## Handline of "Keep Alive" Messages on Home Network If the communication between the IoT Devices and mobile network is IP-based, it may require the use of TCP / UDP "keep alive" messages. In such cases, the IoT Device Application **SHALL** automatically detect the server-specific timers and/or mobile network firewall timers, such TCP\_IDLE value or UDP\_IDLE value (NAT timers as defined by 1NCE GmbH for consumer APN, or by business enterprise for own-administered NAT, in the case of private APN), when using push services. This is achieved by increasing the polling interval dynamically until a mobile network timeout occurs, and then operating just below the timeout value.\ IoT Device Applications communicating with the IoT Server Application over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHOULD NOT** implement TCP / UDP “keep alive” messages on the home network. In IoT Devices, the embedded Service Enablement Layer **SHOULD** implement this requirement in the same way as for IoT Device Applications. ## Data Aggregation, Compression and Transcoding The monolithic IoT Device Application SHALL minimize the number of parallel mobile network connections and overall frequency of connections between the IoT Device and the mobile network. Data is aggregated by the IoT Device Application into an application report before being compressed and sent over the mobile network. Data transcoding and compression techniques are used, as per the IoT Service intended Quality of Service, to reduce connection attempts and data volumes. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement.\ The IoT Device Application **SHOULD** monitor the volume of data it sends and receives over a defined time period. If the volume of data will soon exceed a maximum value defined by the IoT Service Provider (see Suggested Limits), the IoT Device Application sends a report to the IoT Service Platform and stops the regular sending of data until the necessary time period has expired. ## Frequency and Prioritization of Data Transmissions The IoT Device Application **SHOULD** monitor the number of network connections it attempts over a set time period. If the number of connection attempts exceeds a maximum value set by the IoT Service Provider (see Suggested Limits), the IoT Device Application sends a report to the IoT Service Platform and stops requesting mobile network connectivity until the necessary time period has expired. In tiered IoT Devices, the embedded Service Enablement Layer **SHOULD** comply to this requirement.\ IoT Devices Applications communicating with IoT Server Applications over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHALL** optimize their application reporting period to never exceed the IoT Service Provider daily maximum number of messages (see Suggested Limits). ## Localized Communication The IoT Device Application **SHALL** minimize any geographical network loading problems. There **SHALL** be no coordination of all IoT Devices in a given region of the IoT Service to undergo like-operations producing network loading, e.g. firmware updates. ## Adaption to Mobile Network Capabilities, Data Speed and Latency The IoT Device Application **SHALL** be capable of adapting to changes in mobile network feature capability and service exposure. Furthermore, it is designed to cope with variations in mobile network data speed and latency, considering the differences in available throughput, data speed and latency when switching between different 3GPPTM access bearers (i.e. 2G, 3G, LTE and Mobile IoT).\ If data speed and latency is critical to the IoT Service, the IoT Device Application **SHOULD** constantly monitor mobile network speed and connection quality in order to request the appropriate quality of content from the IoT Service Provider’s infrastructure. In tiered IoT Devices, the embedded IoT Service Enablement Layer **SHOULD** constantly monitor mobile network speed and connection quality in order to request the appropriate quality of content from the Cloud Platform. The IoT Device Application retrieves mobile network speed and connection quality information from the IoT Service Enablement Layer. ## Low Power Mode If the IoT Device Application does not need to exchange any data with the IoT Service Platform for a period greater than 24 hours, and the IoT Service can tolerate some latency, the IoT Device **SHOULD** implement a power-saving mode where the device’s communication module/chipset is effectively powered down between data transmissions. This will reduce the IoT Device’s power consumption and reduce mobile network signaling.\ IoT Device Applications communicating over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHOULD NOT** power down their communication module/chipset. The 3GPPTM power saving features **SHOULD** be used instead, thus avoiding power-draining, system selection scanning procedures. ## IoT Service Platform Temporarily Unreachable or Offline If the IoT Service Platform is temporarily offline, the IoT Device Application **SHALL** first diagnose if the communication issues to the server are caused by higher layer communications (TCP/IP, UDP, ATM…). Higher layers mechanisms **SHALL** then try to re-establish the connection with the server. This is done by assessing (and if necessary, attempting to re-establish) connectivity in a step-wise approach, top-down. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. The IoT Device Application **SHALL NOT** frequently initiate an application-driven reboot of the communication module/chipset. The IoT Devices **SHALL** retry connection requests to the IoT Service Platform with an increasing back-off period.\ If the IoT Device detects that the IoT Service Platform is back online, it **SHALL** employ a randomized timer\ to trigger communication requests to the mobile network. ## Coverage Lost (GPS, GLONASS, LAN, WAN) When GPS, GLONASS coverage is lost, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. When LAN or WAN coverage is lost, the monolithic IoT Device **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHALL** retry scanning to acquire mobile network connectivity with an increasing back-off period. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. ## Sensor / Actuator Malfunction When in-built sensors or actuators malfunction, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. ## Sensor Alarms / Actuators Triggered When in-built sensors or actuators are triggered, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** instead send an alert to the IoT Server Application. ## Battery Power Low or Power Failure The IoT Device Application **SHOULD** send a notification to the IoT Service Platform with relevant information when there is an unexpected power outage or battery problem. ## Device Memory Full When the IoT Device memory is full, for example due to the amount of collected data or an unwanted memory leak, the IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. ## Communication Request Fail The IoT Device Application **SHALL** always handle situations when communication requests fail in a way that does not harm the mobile network. The mobile network may reject communication requests from the IoT Device with a 3GPPTM error cause code (refer to GSMA TS.34). When the IoT Device Application detects that its requests are rejected, it **SHALL** retry connection requests to the mobile network with an increasing back-off period. The IoT Device Application **SHALL NOT** start an application-driven reboot of the communication module/chipset, attempting to ignore or override the mobile network’s decision.\ Additionally, the IoT Device Application **SHALL** always be prepared to handle situations when communication requests fail, when such failure is reported by the embedded Service Enablement Layer. Communication requests from the IoT Device Application **SHALL NOT** be retried indefinitely – all requests must eventually time-out and be abandoned by the IoT Device Application. ## Device-Originated SMS are Barred When the IoT Device Application detects that its subscription for MO-SMS is barred by the mobile network, the IoT Device Application **SHALL** retry connection requests to the mobile network with an increasing back-off period. The IoT Device Application **SHALL NOT** start an application-driven reboot of the communication module/chipset. ## Radio Access Technology Bearers Reselection If the IoT Device supports more than one family of access technology (for example 3GPPTM, WLAN) the IoT Device Application **SHALL** employ a randomized delay before switching to a different family of access technology.\ The IoT Device Application **SHALL** implement a protection mechanism to prevent frequent "ping-pong" between these different technologies. This is done by limiting the frequency of reselection actions, with appropriate hysteresis mechanisms. ## Mass Deployments of Devices For mass deployments of IoT Devices (e.g. >10,000 units within the same mobile network), if the monolithic IoT Device supports more than one family of communications access technology (for example 3GPPTM, WLAN) the IoT Device Application **SHALL** employ a randomized delay before switching to a different family of access technology. ## Loss of Roaming Service The IoT Device Application **SHALL** always be prepared to recover lost end-to-end connectivity while camping on a roaming network. This is implemented with a top-down, staged recovery algorithm diagnosing each protocol layer. In case of failing to re-establish one layer, the algorithm initiates the recovery procedure on the following protocol level below. This may be done, for example, as follows: * Step 1. Re-establishment of higher layer connectivity, e.g. VPN tunnels, SSH sessions, etc., * Step 2. Re-establishment of the PDN connectivity or PDP context, * Step 3. Re-attach (data) to the network, * Step 4. Re-triggering of a plain network selection, * Step 5. Complete reboot of the device. All recovery procedures **SHALL**, to avoid excessive sending of signals to the network, be properly implemented. This may include usage of randomized triggers and incremental, back-off retry mechanisms. Threshold and timer values may depend on the IoT Service’s requirements. ## IPv4/v6 Dual Stack Support The IoT Device Application **SHALL** support IPv4/v6 dual stack (PDN Type = IPv4v6) so that it can properly roam onto mobile networks having support for either IPv4 only or IPv6 only or dual stack only. *** # Suggested Limits Please note that these numbers are suggestions which should be noted in the design of an IoT device. Please also note that the metrics are depended on the use case and might be much lower for certain application. These are **NOT** hard limits enforced by 1NCE. ## Suggested Maximum Connection Requests * 2G/3G/4G: 720 connection requests (Network Attach) / day / device (i.e., on average once every two minutes). * NB-IoT/LTE-M: 24 connection requests (Network Attach) / day / device (i.e., on average once per hour). ## Suggested Maximum of Daily Messages * 2G/3G/4G: no limitations * NB-IoT/LTE-M: 120 application messages / day / device (i.e., on average 5 messages per hour); minimal volume per message. ## Suggested Maximum Volume of Data per Single Device * 2G/3G/4G/NB-IoT/LTE-M: 10 Mbytes / month / device; tariff-specific restrictions may occur (e.g., maximum lifetime volume \< 10 Mbytes, or pooling restrictions may be in place limiting the average monthly data volume to 500KB or 1 MB). --- # SMS Services Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/
![Schematic structure of the 1NCE SMS service.](/img/connectivity-services/connectivity-services-sms-services/001.png)
In the world of IoT devices, the Short Message Service (SMS) has still an important role in basic communication with connected devices. The 1NCE SMS Service provides capabilities to send and receive messages with a 1NCE SIM. For more details about this service, refer to the subchapters in the menu on the left side. From the perspective of a device, the 1NCE SMS Service provides the typical sending and receiving possibilities. However, some additional features and limitations for the specific IoT application need to be taken into consideration. In the following sections of this guide, a basic introduction to the features, limitations, terminology, and detailed applications of the SMS service is provided. --- # SMS Examples Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-examples/ --- # Features & Limitations Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-features-limitations/ # Features In addition to sending and receiving MT-SMS, the 1NCE Service offers additional features to provide optimal integration into IoT device workflows and management infrastructures. Details about the implementation and usage of the individual features are available in the individual guide sections. ## Mobile Terminated SMS For sending MT-SMS messages towards an IoT device with a 1NCE SIM, two options are available: * 1NCE Portal: * Submit MT-SMS messages for a single SIM card. * Testing and debugging purposes. * Short-term data retention policy. * 1NCE API: * Submit multiple MT-SMS via automation. * Integration into customer applications possible. * Volume management. * Delivery Reports for MT-SMS. ## Mobile Originated SMS Any device with a 1NCE SIM can send MO-SMS messages. The provided destination mobile number is irrelevant for the delivery process. All MO-SMS messages can be received via two options: * 1NCE Portal: * Low number of messages. * Testing and debugging purposes. * Short-term data retention policy. * 1NCE SMS Forwarder Service: * High number of messages. * Integration into automated customer applications. ## Monitoring SMS Events When an MT-SMS is sent an Event Record is generated. These records can be viewed in the 1NCE Portal or processed through the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) interface. Monitoring the Event Records can help to verify correct device behavior and identify possible connectivity issues. *** # Limitations The 1NCE SMS Service focuses on optimized IoT communication use cases. As a result, some additional limitations compared to the typically expected MT-SMS communication between mobile phones have to be considered. ## SMS Volume Usage Dependent on the tariff of the 1NCE SIM, a certain volume of MT-SMS messages is included. Details about the available volume and usage can be inquired in the 1NCE Portal or through the [1NCE API](/api/). Each MT-SMS message sent (MT or MO) counts towards the used volume. Delivery retry attempts are not counted towards the volume. Once the volume is used up, no more messages can be sent until the volume is topped up. ## SMS Size Limitations The typical limitations of the MT-SMS size also apply to 1NCE SMS. A message can be at most 160 characters long. Longer messages must be split into multiple messages. It is possible to send concatenated MT-SMS via API requests. ## Device-To-Device SMS (P2P) With 1NCE connectivity, it is not possible to send Peer-to-Peer (P2P) MT-SMS between devices. Therefore, it is not possible to send a message to a device with a 1NCE SIM using a mobile phone, neither with a third party nor another 1NCE SIM. For instance, it is possible to set the destination number on a mobile phone and send a message to this number but the Short Message Service Centre (SMSC) will not forward this MT-SMS to the destination number. The MT-SMS service is only intended to exchange messages with a server application controlled by the customer, Application-to-Peer (A2P).
![Schematic diagram showing that SMS to external sources are not supported.](/img/connectivity-services/connectivity-services-sms-services/sms-services-features-limitations/001.png)
## SMS over NB-IoT 1NCE core does not support IP messaging and hence, the devices must receive the message while being connected to the GSM network. Furthermore, while being connected to NB-IoT the dispatch or reception of MT-SMS is not possible. ## SMS Expiry Date & Retry For the case the subscriber is not reachable via MT-SMS, an expiry date can be set which is used to retry the delivery of the MT-SMS. The following sections will cover this behavior in detail. ### MO-SMS When sending a MO-SMS towards a customer-server application using the SMS Forwarding Service, the default delivery expiry time is 24 hours. The delivery retry scheme works exponentially, i.e. the period between the different delivery attempts increases with each attempt. If delivery fails in the first attempt, due to the server being down or an incorrect Forwarding Service setup, the MO-SMS is buffered. In that case, for instance the 1st retry is done after 5 minutes, the 2nd after 15 minutes, each retry counting from the submit time. In case the message cannot be delivered with the default time of 24h, the MO-SMS will expire and no more retry takes place. ### MT-SMS A MT-SMS sent towards a device with a 1NCE SIM, the default expiry time is 24 hours if the message was submitted through the 1NCE Portal. When using the 1NCE API, the expiry time can be changed by customer. If the device with the 1NCE SIM is not reachable at the point of time when the MT-SMS was submitted, the retry mechanism will deliver the message as soon as the SIM attaches to the network the next time and is ready to receive messages, provided the MT-SMS has not expired. ### SMS Validity Time & Data Retention Due to General Data Protection Regulation (GDPR) and the 1NCE data retention policy, a MT-SMS is stored at most seven days. After this period 1NCE deletes the MT-SMS data from the system and the content is no longer available. Therefore, it is recommended to set up the SMS Forwarding Service and Data Streamer Service for using the 1NCE SMS Service to the full extend. ### Originator Address/Number Some devices and network operators require that an originate address or number is provided, otherwise some devices or MNOs will not accept the SMS messages. This originator address does not need to be configured to a specific SIM parameter in the 1NCE IoT domain. Any random numbering should work in this case as any returned SMS from the device are always send to the 1NCE Portal to SMS Forwarder. Please fill out this data when sending SMS via API or 1NCE Portal. --- # Mobile Originated SMS Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-mo-sms/
![Schematic sequence diagram of a MO-SMS message.](/img/connectivity-services/connectivity-services-sms-services/sms-services-mo-sms/001.png)
SMS messages originating from a device with a 1NCE SIM are referred to as Mobile Originated SMS (MO-SMS). Messages sent from an IoT devices with 1NCE SIM are only forwarded to application targets and not other devices. For accessing and receiving the messages, 1NCE offers multiple solutions for different needs. References to examples for all the listed methods are provided. *** # 1NCE Portal The most basic option to receive and visualize MO-SMS is the 1NCE Portal. In the web user interface, the messages and timestamps for individual SIM can be viewed. This is useful for debugging and testing with a limited amount of SIM cards. The data shown in the portal will be retained for seven days. Afterward, the records of the received SMS will no longer be visible. For more details about the usage of the portal, refer to the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. See the [MO-SMS Portal Examples](/docs/blueprints-examples/examples-sms/examples-mo-sms#1nce-portal--sms-console) for an example of MO-SMS in the 1NCE Portal. *** # Management API Besides monitoring SMS relevant parameters via the 1NCE API, it is also possible to query messages for specific SIM from the API. This application is meant for infrequent queries of a small number of messages, e.g. for testing purposes. Although it would be possible to query SMS messages for all SIM regularly, it is not recommended to create unnecessary HTTP Requests and loads on the API. A better solution for receiving large amounts of SMS messages regularly is the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/). The process of querying messages with the API and HTTP Requests is described in the [1NCE API](/api/) documentation. See the [MO-SMS API Examples](/docs/blueprints-examples/examples-sms/examples-mo-sms#1nce-sms-api) for example usage of the 1NCE API for MO-SMS. *** # SMS Forwarding Service For receiving SMS messages in an automated way, the SMS Forwarding Service is the ideal solution. It allows getting push messages via a customer-specified HTTP REST interface. Details about the Forwarding Service can be found in the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) guide. See the [SMS Forwarder Examples](/docs/blueprints-examples/examples-sms-forwarder/) for examples on how to setup, test and use the SMS Forwarder Service. --- # Mobile Terminated SMS Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-mt-sms/
![Schematic diagram of a MT-SMS message.](/img/connectivity-services/connectivity-services-sms-services/sms-services-mt-sms/001.png)
The term Mobile Terminated SMS (MT-SMS) encompasses SMS messages destined for a specific device. As 1NCE connectivity focuses on IoT applications, sending SMS messages from device to device (P2P) is not possible. Therefore, sending messages from a phone or other device towards a terminal with a 1NCE SIM is not possible. The 1NCE SMS Service offers two methods of sending messages towards an device. Please note that some devices require an originator address/number to be set in order to successfully receive an SMS. In the 1NCE IoT use case, the number does not need to match any specific number of the SIM. *** # 1NCE Portal An easy-to-use and very intuitive tool for sending MT-SMS to individual devices with 1NCE SIM is the 1NCE Portal. This method is ideal for debugging and testing purposes as it offers an easy-to-use user interface for sending and monitoring SMS messages. Details on using the portal interface for sending SMS to devices can be found in the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. For sending and receiving larger amounts of SMS and automating this process over longer periods, the 1NCE API is recommended. See also the [MT-SMS Portal Examples](/docs/blueprints-examples/examples-sms/examples-mt-sms#1nce-portal--sms-console) for an example of MT-SMS in the 1NCE Portal. *** # 1NCE SMS API For larger batches or automated messages, the 1NCE API offers a HTTP REST interface for processing requests. Compared to the 1NCE Portal, the API offers more flexibility for automation and optional configuration of advanced SMS parameters (UDH, DCS and Expiry Date). The Data Coding Scheme (DCS) parameter enables GSM 7-bit default alphabet text messages and 8-bit binary data messages. The User Data Header (UDH) is an optional parameter which specifies how a message should be formatted and processed. It is useful for sending concatenated SMS messages consisting of two or more parts. How concatenated messages can be submitted is shown in the [Concatenated SMS Messages](#concatenated-sms-messages) section. See also the [MT-SMS API Examples](/docs/blueprints-examples/examples-sms/examples-mt-sms#1nce-sms-api) for references to sending SMS via API. ## Data Coding Scheme The Data Coding Scheme (DCS) is a value which transports information about how the recipient device shall handle the the transferred data payload. In principle, the DCS specifies the character set of your payload. Based on the chosen DCS the message length varies. The maximum length of a SMS is 160 character using the default GSM character set. You can use another character set and the maximum number of characters which can be used might shrink. In the following table you can see some DCS values and its short descriptions. For a full reference please see Data Coding Scheme Wiki. | DCS Value | Format | Payload for API | | --- | --- | --- | | 0 | 7-Bit Alphabet Text | Message Payload as String *TestSMS* | | 4 | 8-Bit Binary Data | Binary Payload as Hex Encoded String *54657374534d53* | | 8 | UCS-2 | | ## Concatenated SMS Messages In the User Data Header (UDH), the format and processing of an SMS message is specified. This header information is useful for sending a concatenated message which is longer than the 160 character limit. To split a message into multiple parts, each part needs to be sent via a separate API call with the correct UDH header. An example is shown below: | Part Number | User Data Header | Payload | | :---------- | :--------------- | :-------------- | | 1 of 3 | 050003CC 03 01 | Message Part 01 | | 2 of 3 | 050003CC 03 02 | Message Part 02 | | 3 of 3 | 050003CC 03 03 | Message Part 03 | The UDH needs to be accounted for in the total size of the SMS message. Therefore, only 153 7-bit character parts can be sent in one message when the UDH is used to concatenate messages. The UDH consists of six-byte fields: * The total length of UDH * The Information Element Identifier (IEI) * The header length without the first two fields (IEIL) * CSMS reference ID * Total number of SMS parts * Part number For more information about the UDH and SMS concatenation see GSM 03.38 and GSM 03.40. *** # SMS Forwarder Service While it is not possible to directly send MT-SMS with the SMS Forwarding Service, it is possible to receive Delivery Reports (DLR). These reports are sent via the configured forwarding URL, indicating that the MT-SMS was delivered to the target device with a 1NCE SIM. Further details about this service can be found in the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) section. --- # SMS Monitoring Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-sms-monitoring/ Besides sending and receiving MT-SMS and MO-SMS messages, 1NCE offers additional ways to monitor the flow of messages and retrieve log data. Three options are available to explore and gather data for monitoring purposes: 1NCE Portal, 1NCE Data Streamer Service and 1NCE API. In the following sections, the capabilities and benefits of each available interface is presented. *** # 1NCE Portal The 1NCE Portal offers an easy and ready-to-use user interface for monitoring 1NCE services. Regarding SMS services, the overall volume usage and status of messages for each SIM is presented in the portal. Furthermore, the SMS Console offers the functionality to send and receive messages using the web interface. The Event Records from the Data Streamer are listed as part of the user interface. This provides a quick overview of the current events of the 1NCE SIM. Overall the portal offers a good starting point for manual monitoring of small amounts of SIM or easy debugging. The portal offers no automation integration and logging data is deleted after seven days due to the data retention policy. For more details on how to use the 1NCE Portal, please refer to the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. *** # Data Streamer The Data Streamer offers a stream of Event and/or Usage Records via a wide selection of cloud connectivity applications. This service is ideal for long-term, automated monitoring of a large amount of connected SIM. Regarding the SMS services, the message usage volume and event records for the SMS Forwarding Service are included in the Data Streamer. Upon sending or receiving a message a Usage Record entry is sent via the streaming service, showing the used volume for sending a message. The Event Records also log errors from the SMS Forwarding Service. If the provided REST endpoint is not reachable or does not meet the required configuration, a HTTP 500 Error Event will be logged in the Data Streamer. In this case, please verify the configuration and availability of the provided HTTP endpoint. More details are covered in the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) section. *** # SMS Forwarder A further source for monitoring of the SMS Service, including Delivery Reports, MT-SMS, MO-SMS messages and status information is available through the SMS Forwarding Service. Please refer to the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) section for more details. *** # SMS API The 1NCE API does not only allow to send SMS messages via HTTP Requests, but also offers endpoints to query information about the SIM and SMS service on demand and set up certain additional parameters. This includes SMS Volume usage and limits, status messages, old messages with payload, etc. Please note that this data for the API will be held at most seven days, due to the data retention policy. The API is ideal for requesting specific debugging information on demand. It is not recommended to use the API for large automated queries on a regular basis, please use the Data Streaming Service for this automation. Details about the API can be found in the [API](/api/) section of the documentation. --- # SMS Volume Source: https://help.1nce.com/docs/connectivity-services/connectivity-services-sms-services/sms-services-sms-volume/ Dependent on the tariff of the 1NCE SIM, a certain volume of SMS message volume is included. The current state of the volume for each of the SIM can be either viewed in the 1NCE Portal or queried through the [1NCE API](/api/). The following sections will explain what is counted towards the SMS volume usage and list a few example showcases. *** # SMS Volume Usage Using a 1NCE SIM and the SMS Service, each MT-SMS and MO-SMS message count towards the used volume. Important to note is that both "sending" and "receiving" SMS messages from the view of a 1NCE SIM card are considered as usage. Delivery retry attempts, Delivery Reports, the SMS Forwarding Service, and SMS API requests are not counted towards the volume. MT-SMS that are not successfully delivered to a device will not be billed towards the used SMS volume. For MO-SMS, the usage is counted even if the SMS Forwarding Service is not configured as the the SMS is still delivered to the 1NCE backend and displayed in the 1NCE Portal for ease of use. Once the SMS volume is used up, no more messages can be sent until the volume is topped up. Trying to send a message if the volume is used up will result in a Warning Event in the Data Streamer. *** # Self-Set SMS Volume Limits A customer-specified limit for the MO-/MT-SMS message volume can be set in the 1NCE Portal Configuration tab or through the 1NCE API. This limit applies to the SMS message volume for all SIM in the organization. These limits can be used to restrict the message volume usage per month for the SIMs from the network side. The limits can be set in predetermined steps and will be reset on the first day of each new month. ## Reaching and Resetting the Limit If a SIM runs into this limitation, an error message will be issued when submitting a new SMS message through the API **Traffic limit of X SMS per month exceeded** or 1NCE Portal **Set monthly limit of SMS exceeded**. To reenable a SIM, please either wait until the volume is reset at the beginning of the month or manually increate the limit via the 1NCE Portal Configuration tab or 1NCE API. Sending a MO-SMS while the MO-SMS message limit is exceeded, will result in the SMS being rejected to the 1NCE Network. This rejection will result in an error return code from the device modem. > ❗️ Error Warning Exceeded Limit > > Using the 1NCE API if the self-set limit is reached **Traffic limit of X SMS per month exceeded** is returned as error. In the 1NCE Portal **Set monthly limit of SMS exceeded** is shown when the SMS limit was reached and a new SMS is issued.\ > For **MO-SMS** no notification will be shown in the 1NCE Portal or Data Stream. The SMS will be rejected by the network resulting in an error return code from the device modem. *** # Example SMS Usage Scenarios ## One MT/MO-SMS Sending **one** MT-SMS or MO-SMS will charge **one** SMS towards the included volume. ## MT-SMS with MO-SMS Answer The customer sends one MT-SMS via the 1NCE API towards the device, and the device responds with a MO-SMS back towards the customer. In this case, **one** MT-SMS and **one** MO-SMS are sent, resulting in a volume deduction of **two** SMS messages. --- # Internet Breakout Source: https://help.1nce.com/docs/network-services/network-services-internet-breakout/
![](/img/network-services/network-services-internet-breakout/001.png)
The default connectivity for a 1NCE SIM is achieved through the Internet Breakout Service. All devices with a 1NCE SIM can connect freely to services hosted in the public internet space. The Figure above illustrates the basic operation principle of the 1NCE Internet Breakout. Please note that the IPs listed in the Figure are just example placeholders. For the Internet Breakout IPs please refer to the list below for the full available IP pool. Depended on the configured breakout setting in the 1NCE Portal, the behavior of the Internet Breakout will different. *** # Internet Breakout Modes The Internet Breakout setting in the configuration tab allows you to configure the ideal network flow for your SIMs cards for public-facing internet access and private connectivity through VPN. The 1NCE Internet Breakout can be configured in two different variances, which offer different functionality. * Automatic Mode * Manual Mode The breakout setting allows you to select the nearest local Internet Breakout to minimize latency in data transfer. Your SIM card can either **Automatically** select the geographically nearest breakout, or you can **Manually** set the location of the breakout. > 📘 Default Setting > > With the release (20.09.2022) of the configurable Internet Breakout setting, existing customers breakout will remain as Europe (Frankfurt) as before the feature introduction. > > New Organizations and newly created Suborganizations will use the Automatic Mode by default. This setting can be changed in the 1NCE Portal configuration tab. ## Automatic Mode When using the Automatic Mode, **each individual SIM** data traffic towards the public internet is routed through the geographically optimized data center based on the SIM location to allow for low latency internet access. The automatic system selected the ideal breakout region for each individual SIM independently. This results in SIMs exiting through different breakouts dependent on their location. 1NCE is using AWS to facilitate dynamic Internet Breakout in the Automatic Mode. The closest breakout region is dynamically chosen based on the device location. Different availability zones inside the breakout region serve as backup to prevent downtime. > 📘 VPN and 1NCE OS > > OpenVPN and 1NCE OS Services are currently not available in the **Automatic Mode** due to the automatically changing breakout IPs. While Automatic Mode is active, the OpenVPN Configuration tab is disabled. ### Example Configurations One customer SIM device is located and connected in Germany. Based on the given location, the automatic Internet Breakout determines that the Europe (Frankfurt) is the ideal location to breakout the public internet traffic. The customer can expect their public internet traffic to exit from one of the breakout IPs from Europe (Frankfurt). A second SIM device is located and connected in New York USA. As the SIM devices is closest to the US East breakout, the automatic system determines that US East (N. Virginia) should be used to exit the public internet traffic of the SIM. The traffic from this specific SIM will exit through the US East (N. Virginia) Internet Breakout IPs. ## Manual Mode When selecting a specific breakout region using the Manual Mode, **all SIMs** public internet access will be routed through the selected breakout region. All SIMs of the customer (sub) organization are locked to the selected manual breakout region, independent on the actual device location. > 📘 VPN and 1NCE OS > > The 1NCE VPN Service is available in the **Manual Mode**. The specific regional adaptions of the [OpenVPN Configuration](/docs/1nce-portal/portal-configuration#openvpn-configuration) need to be applied. > > 1NCE OS is currently only available through the Europe (Frankfurt) and US East (N Virginia) breakout regions. Currently, five regions are available: * Europe (Frankfurt) * US West (N. California) * US East (N. Virginia) * Asia-Pacific (Tokyo) * South America (São Paulo) ### Example Configurations The Manual Mode is set to Europe (Frankfurt) for the example organization. One customer SIM device is located and connected in Germany. Independent of the given location, the manual Internet Breakout Europe (Frankfurt) is used to breakout the public internet traffic. The customer can expect their public internet traffic to exit from one of the breakout IPs from Europe (Frankfurt). A second SIM device is located and connected in New York USA. The SIM devices is closest to the US East breakout, but due to the Manual Mode, the traffic will be routed through the Europe (Frankfurt) exit to the public internet. The traffic from this specific SIM will exit through the Europe (Frankfurt) Internet Breakout IPs. ## Optimized Breakout Countries Using the automatic breakout mode, the traffic of SIM devices will switch breakout based on the operator to which the device is connected. With the automatic mode, this switching is automatically optimized to deliver the lowest latency possible through an internet breakout. When using a manual breakout the list of optimized countries should also be considered. Selecting a manual breakout for a non-optimized country or operator could lead to worse latency overall. Therefore it only makes sense to change the manual breakout if the SIM devices are located within the optimized countries. ### United States Please note that our US breakouts are currently optimized for SIM cards deployed and roaming within the USA. For this reason it is impossible to take advantage of their benefits if a SIM is located outside the country. We are already working on a timely global extension. ### Asia-Pacific Breakout For the following countries, the Asia-Pacific breakout will be used in automatic mode. When using the manual breakout configuration, switching to Asia-Pacific is beneficial if most SIM devices are located within these regions: Australia, Cambodia*, China, Hong Kong, Indonesia, Japan, South Korea, Malaysia*, Mongolia, New Caledonia, New Zealand, Philippines, Sri Lanka, Taiwan*, Thailand*. *not for all operators in the country {/* ### South America (São Paulo) */} *** # Internet Breakout IPs Each available Breakout Region has its unique set of IP Addresses. The specific IP address selected for the Internet Breakout of a SIM card is randomly chosen and can not be managed by the customer. Depending on your configuration, all IPs or Region-specific ones should be used for whitelisting the 1NCE Internet Breakout service. Note that the used IPs are depended on the selected Breakout Mode: * **Automatic mode**: all IP addresses * **Manual Mode**: IPs matching the configured Region ## List of IP Addresses The currently used IPs to breakout any internet-targeted traffic are listed below. Please note that these IP addresses might change overtime as new resources and features upgrades are introduced. ### Europe (Frankfurt) | | | |---|---| | `18.197.48.88` | `18.196.213.123` | | `18.158.164.113` | `18.159.233.211` | | `18.159.81.202` | `18.184.88.141` | | `18.193.1.150` | `18.193.152.39` | | `18.195.228.33` | `18.195.39.164` | | `18.196.220.3` | `18.198.73.229` | | `3.122.48.136` | `3.124.161.167` | | `3.125.204.250` | `3.127.225.197` | | `3.69.185.69` | `3.70.63.102` | | `3.72.206.109` | `3.72.220.2` | | `3.74.239.61` | `3.76.234.36` | | `3.76.246.25` | `3.76.71.73` | | `3.77.128.21` | `3.78.103.144` | | `3.78.105.161` | `3.78.11.129` | | `3.78.118.82` | `3.78.22.61` | | `3.78.30.118` | `3.78.54.227` | | `3.78.80.178` | `52.58.166.184` | ### US West (N. California) | | | |---|---| | `13.52.88.115` | `13.56.127.98` | | `184.72.14.243` | `50.18.219.28` | | `54.151.43.39` | `54.176.42.26` | | `54.177.224.205` | `54.177.237.57` | | `54.183.119.255` | `54.215.48.106` | | `54.215.50.114` | `54.219.94.206` | | `54.241.17.235` | `54.241.255.162` | | `54.241.50.173` | `54.67.92.20` | ### US East (N. Virginia) | | | |---|---| | `23.23.138.167` | `3.222.175.158` | | `3.222.216.109` | `3.225.189.15` | | `3.227.104.16` | `34.192.19.93` | | `34.194.27.192` | `34.224.157.70` | | `34.225.144.128` | `34.225.189.236` | | `34.236.129.19` | `35.171.69.69` | | `35.172.74.1` | `52.200.197.12` | | `52.204.165.12` | `54.156.152.87` | | `23.22.227.77` | `3.219.123.171` | | `3.93.91.86` | `34.234.186.137` | | `44.210.17.192` | `44.213.243.128` | | `52.45.143.123` | `52.55.140.49` | ### Asia-Pacific (Tokyo) | | | |---|---| | `3.112.185.7` | `3.114.177.168` | | `18.178.179.20` | `18.180.11.40` | | `18.181.5.226` | `18.181.6.50` | | `35.74.89.95` | `43.206.70.243` | | `52.196.96.15` | `52.198.214.172` | | `52.199.139.92` | `54.64.108.231` | | `54.64.136.175` | `54.95.160.207` | | `54.168.158.172` | `54.250.103.58` | ### South America (São Paulo) | | | |---|---| | `15.229.196.161` | `18.228.115.195` | | `18.228.53.212` | `18.229.25.47` | | `52.67.10.199` | `54.232.172.76` | | `54.232.208.147` | `54.233.120.112` | | `177.71.193.95` | `18.228.164.80` | | `18.228.87.71` | `18.230.109.14` | | `52.67.255.187` | `54.232.201.155` | | `54.232.210.47` | `54.94.135.62` | ## Data Streamer and SMS Forwarder IPs The public IPs for Europe (Frankfurt) Region are additionally used for the 1NCE Data Streamer and SMS Forwarder Service. Whitelisting the Europe (Frankfurt) IPs is required for using these services as these are operated independently of the configured Breakout Region. *** # Network Address Translation By design, the internet access for 1NCE SIMs is implemented with Network Address Translation (NAT). The NAT maps the private SIM-IP to commonly used public 1NCE breakout IP. This network design simplifies IP space management and enhances the access security of connected IoT devices. As a result, devices with a 1NCE SIM cannot be directly accessed from the public internet side, thus improving the resilience against external attacks and threads targeting the IoT devices. Using the 1NCE Internet Breakout, the **connection establishment** is **unidirectional** (e.g., SIM towards server/service), while **data transfer** over an already **established connection** is **bidirectional** (e.g., SIM towards server/service and server/service towards SIM). The flow of the 1NCE Internet Breakout is shown in the sequence diagram below. Bidirectional connection establishment can only be achieved using the 1NCE VPN Service.
![Sequence diagram of the 1NCE Internet Breakout.](/img/network-services/network-services-internet-breakout/002.png)
*** # Data Protocols The concept of the Open Systems Interconnection model applies to the 1NCE Data Service structure. The GPRS Tunneling Protocol (GTP) is used on layer 3 to transfer user application data between the device with a 1NCE SIM and the internet or application server and vice versa. All the data traffic is wrapped in the GTP, on top of this protocol (layer 4+) the customer is free to use any transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port assignment. *** # Domain Name System (DNS) The Domain Name System (DNS) is used to resolve Uniform Resource Locators (URL) to an addressable IP. When using the 1NCE Internet Breakout, the public IP `8.8.8.8` is served as primary and `8.8.4.4` as secondary default Domain Name Server. A manual configuration of a DNS on the device is typically not needed but can be configured, if desired. *** # Maximum Transmission Unit (MTU) Size The Maximum Transmission Unit (MTU) is the size of the largest IP packet (layer 4) possible which can be transferred in a respective frame on layer 3 without the need for fragmentation in the packet based core network. If a send packet is larger than the specified MTU, the packet needs to be fragmented, thus creating more overhead and delays. Theoretically, a size of 1500 bytes is possible with the 1NCE Data Service. Based on prior experience with IoT devices and mobile networks, it is recommended to keep the **MTU size lower than about 1200 bytes**. *** # Internet Breakout Timeout The Internet Breakout does not have a static NAT timeout for pending connections. Please consider that timeouts for inactive TCP and UDP connections. For established TCP connections the timeout is 600 seconds and for UDP the timeout is 120 seconds. After the respective timeout and no further data transmission, the TCP /UDP connections will be closed. New TCP and UDP connections can be opened at any point of time, there is no need to reattach the SIM device with a new PDP. *** # Breakout IP Blacklisting The traffic from all 1NCE SIMs towards the public internet is routed through a NAT with a the listed public-facing IP addresses. These public breakout IPs are listed above under Internet Breakout IPs. The specific IP address selected for the Internet Breakout is randomly chosen and can not be managed by the customer. > ❗️ Whitelist 1NCE Breakout IPs > > Ensure that the 1NCE Internet Breakout IPs are whitelisted for custom service infrastructure accessed by 1NCE SIMs through the Internet Breakout. Large quantities of SIMs accessing the same service can lead automated firewall and protection mechanisms to block the 1NCE Breakout IPs. All requests towards public internet services appear to come from these IPs. Most public services and APIs (e.g. time services, open source APIs, etc.) apply a request limit and smart filtering to detect and filter out denial of service (DDoS) and similar attacks. Very frequent queries (e.g., every second) from multiple SIMs towards one endpoint could trigger these filtering mechanisms. This will result in the public service blocking requests from 1NCE SIM devices, rendering the service unusable. Most public services cannot differentiate between individual SIMs due to the 1NCE NAT network structure. It is strongly recommended to program devices with 1NCE SIMs in a way that they do not aggressively query such shared resources. Using customer-controlled resources (e.g. custom server, AWS or similar cloud service), the protection control mechanisms can be configured to whitelist the traffic originating from the 1NCE NAT Breakout. --- # VPN Service Source: https://help.1nce.com/docs/network-services/network-services-vpn-service/
![](/img/network-services/network-services-vpn-service/001.png)
Each 1NCE SIM has a private IP and is connected via the Internet Breakout using Network Address Translation to the public internet. By default the connection establishment is unidirectional from the SIM device to a server/service in the internet. The 1NCE VPN Service enables 1NCE customers to connect and transmit data bidirectional with their SIM devices via a Virtual Private Network (VPN) connection. A VPN describes a technology that encapsulates and transmits Internet Protocol (IP) network data, over a separate network. Virtual Private Networks are commonly used to enable access to parts of a network that are otherwise inaccessible from the open internet. 1NCE uses the open-source implementation OpenVPN as the basis for the VPN Service. The Figure provides a high-level overview of the VPN Service. The VPN provides mutual communication between devices with a SIM and their application server endpoints with the VPN client. The 1NCE VPN Service is available in Manual Mode for the selected Breakout Setting and the usage of this service is optional and free of charge. Even if the VPN Service is used, the default NAT Internet Breakout is still available for requests towards the internet using. 1NCE provides three different OpenVPN Server Endpoints matching each available Breakout region that can be configured. --- # Features & Limitations Source: https://help.1nce.com/docs/network-services/network-services-vpn-service/vpn-service-features-limitations/
![](/img/network-services/network-services-vpn-service/vpn-service-features-limitations/001.png)
This chapter provides a high-level, abstract overview of the features and limitations of the 1NCE VPN Service. It shows the extended possibilities and benefits of the VPN, compared to the regular Internet Breakout capabilities of the 1NCE SIM. In addition, the limitations of the service are pointed out. *** # Features The 1NCE VPN Service is available in Manual Mode for the selected Breakout Setting and the usage of this service is optional and free of charge. In the following section, the main features and function of this service will be shown. ## Bidirectional Communication Establishment Compared to the default Internet Breakout capabilities of the 1NCE SIM Connectivity, the VPN Service allows bidirectional communication establishment (see Figure above). An IoT device with a 1NCE SIM can communicate directly to an application server by addressing the VPN client endpoint IP of this server. Vise versa, the application server can reach a listening 1NCE SIM device with an active PDP context (data session) via the VPN tunnel interface by setting up the communication to the static IP addresses of the SIM. This setup is required for the server-to-device initiated communication using common Internet Protocols or remote SSH connections to access the mobile device. The customer is free to use any user transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port number over the VPN connection. ## Internet Breakout As the 1NCE VPN Service is available in parallel with the normal Internet Breakout connectivity, a device with a 1NCE SIM can still use the normal internet connectivity while the VPN connection is established. This has the benefit that sensitive data can be sent via the VPN endpoint IP address to a server, but general requests (e.g., NTP or public API queries) can be directly done by the device without the need to set up forwarding internet traffic through the VPN connection. The 1NCE VPN Service is not available if the Automatic Mode for the Internet Breakout is used. For using the 1NCE VPN Service, please set a manual Internet Breakout Region. The VPN configuration is specific for each individual Breakout Region. Please download the matching VPN config from the 1NCE Portal. After a change in the breakout settings, the VPN client needs to be altered with the region-specific configuration. One VPN client at a time can be used and each VPN client IP will be different per breakout region. The client IP for each region is static with the given credentials but might change e.g. due to a customer requested token update. 1NCE always suggests to use DNS to dynamically resolve the private VPN client IP on the SIM devices. Hardcoding the IP address of any component such as VPN client or SIM device is not recommended. ## Enhanced Security The 1NCE VPN Service offers overall improved connection security. All SIM-related traffic exchanged between the 1NCE Core network and the customer application server can be sent over the VPN connection by using the assigned SIM or IP ranges respectively. This private virtual network offers direct access to the SIM with no other public traffic to worry about and filter. All tunnel traffic is handled over one port and connection, which is easier to integrate and maintain. ## No Additional Cost The 1NCE VPN Service is included for all 1NCE SIM customers and is not extra charged. The usage of the VPN does not produce more overhead with regards to the data volume usage. Transmitting data via the default Internet Breakout or the 1NCE VPN Service will result in the same usage of data volume for the SIM. All the traffic sent and received by a SIM is accounted as volume usage independent of the VPN usage. ## Globally distributed Servers The 1NCE VPN Service is available in all three Breakout Regions for selection in the Manual Mode. Each Breakout provides a dedicated OpenVPN Server to provide the flexibility to select the closest location to your application server. *** # Limitations Due to technical constraints, certain limitations apply to the 1NCE VPN Service, which needs to be taken into consideration. ## OpenVPN Version 3 Currently version 3 of the OpenVPN client is not natively supported by the 1NCE VPN Service. It is recommended to use the latest OpenVPN version 2.x for connecting to the VPN and using the direct SIM data connection. ## OpenVPN Version 2.6.x Updates For customers upgrading their existing OpenVPN version to 2.6 and above might need to download a new 1NCE configuration file from the 1NCE Portal. Some parameters were optimized for the newer versions of OpenVPN, the basic configuration and IP addresses will remain the same as before. ## VPN Connection Limit The 1NCE VPN Service supports one active VPN client connection per (sub-) organization (see Figure below) at a time. If multiple clients try to connect at the same time, inconsistent data connections with random disconnects between the clients will occur. For establishing multiple connections to the 1NCE network, please refer to the IPSec Service or create additional suborganizations. Every (sub-) organization receives its own access data.
![Overview showing that multiple VPN connections are not possible.](/img/network-services/network-services-vpn-service/vpn-service-features-limitations/002.png)
## VPN Client IP Routes When the OpenVPN client establishes as connection to the VPN server all required network routes will be pushed to the client, ensuring that all SIM cards of an organization can be reached from the client. There will be one network route entry per assigned IP address space. Though the OpenVPN server does not push changes in routes while a VPN connection is established. Consequently, the OpenVPN must be restarted to receive routes for additional IP address spaces. If you have received additional SIM cards you may want to check the 1NCE Portal if any new IP address spaces were added to your organization. > ❗️ New IP Spaces > > Please restart your VPN connection if you ordered a large new batch of SIMs which received a different IP Space range. ## Conflicting IP Ranges As 1NCE uses private IP spaces (RFC 1597) for the connectivity SIM and OpenVPN client, there is a chance for an IP address conflict if the same IP address range is used in your local network or data center. To resolve this issue, the local network IP addresses can be changed or the 1NCE VPN Service access needs to be segregated from the rest of the affected network. ## VPN Client Password Length Some OpenVPN client implementations are limited to a password length of smaller than 128 characters. As the credentials provided by the 1NCE VPN Service are longer than this limitation, in rare cases this will cause an AUTH\_FAILED response when connecting to the VPN server. This issue can be mitigated by upgrading to a more recent OpenVPN implementation or changing the password length parameter during compiling. In the case an update is possible, we recommend to implement the VPN Client Service on a different server system. If an update or other deployment is not possible and the issue is consistent, please contact the 1NCE support for further advice. ## Default Traffic Routing When using the 1NCE VPN Service, only data routed by the single connected device towards the OpenVPN Client IP is actually sent to the customer-side VPN endpoint. All other traffic is transmitted using the default Internet Breakout. For an application case where all traffic (DNS , NTP, etc.) should be accessible through the VPN , the routes on the connected device with the 1NCE SIM needs to be adapted by the customer. ## Maximum Transmission Unit Size Using the 1NCE VPN, some device connections might have issues with the Maximum Transmission Unit (MTU) size. A symptom is often that larger payloads do not get delivered. To avoid this issue, please lower the MTU to 1300 using the `tun-mtu 1300` configuration parameter in the VPN client configuration. ## Internet Breakout Region VPN is not available if the Automatic Mode for the Internet Breakout is used. To use the VPN Service, please set a manual Internet Breakout Region. The VPN configuration is specific for each individual Breakout Region. Therefore, after a change in the breakout setting the VPN client needs to be altered with the region-specific configuration. The VPN client IP will be different for each of the possible Internet Breakout Regions. This needs to be taken into consideration when designing the SIM device firmware. ## Inactive VPN Connection Deactivation VPN connections not actively in use should be disconnected by the customer. After three months of VPN inactivity, 1NCE reserves the right to deactivate the VPN connection from the core network side. This measure helps to maintain network efficiency and security. If a VPN connection has been deactivated due to inactivity, the existing VPN configuration will no longer be operational. To resume VPN service usage, a new credential file must be downloaded from the 1NCE Customer Portal and the connection must be reconfigured. --- # OpenVPN Files Source: https://help.1nce.com/docs/network-services/network-services-vpn-service/vpn-service-openvpn-files/ > 📘 OpenVPN Files Download > > Both the configuration and credential file can be downloaded from the configuration page of the 1NCE Portal. This section provides a general description of the tunnel interface of the VPN Service as well as an overview of the configuration and credential files. For setup and testing guides for different operating systems, please refer to the VPN Setup Guide. *** Tunnel Interface Connecting the VPN client on PC or server creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. For opening or pinging a server to SIM device connection it is important that the SIM is attached to the network and the device modem has an active PDP data session open. *** # OpenVPN Configuration Files VPN Client File When downloading the VPN configuration file (see extract below), two different file formats for Windows and Linux are available. The content of both files is almost identical. The only difference is the `auth-user-pass` entry in the file. This line points the VPN client towards the `credentials.txt` file for authenticating the user on the VPN server. The default path is different for the two operating systems but can be changed to the specific of the operating system or VPN client. The `remote` address and port of the VPN server should not be changed. It has to be ensured that both the domain address and the given port are configured in any firewall or access system to allow a connection towards the 1NCE VPN server. The table below shows the default config provided by 1NCE. Some parameters can be **adapted** (✔) while others should be **not changed** (❌). 1NCE does not recommend changing or altering the default configuration and does not guarantee that changes in the configuration will provide the expected connectivity. | Config Parameter | Default Value | Customizable | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------: | :----------: | | **client** Indicates that the `xx-region-x-client.ovpn` file is a client configuration. | | ❌ | | **dev** Virtual network device set to Tunnel (TUN), simulates a network layer device and operates with layer 3 IPv4 and IPv6 packets. Tunnel interface name can be changed to `tun` where `` is a integer number. | `tun` | ✔ | | **proto** Protocol setting for communicating with remote host. | `udp` | ❌ | | **remote** Remote host name or IP address. | ` ` | ❌ | | **resolv-retry** If hostname resolve fails for –remote, retry resolve for n seconds before failing. | `infinite` | ✔ | | **nobind** Do not bind to local address and port. The IP stack will allocate a dynamic port for returning packets. | | ❌ | | **explicit-exit-notify** Send server an exit notification if tunnel is restarted or OpenVPN process is exited. Number of attempts that the client will try to resend the exit notification. | `3` | ❌ | | **keepalive** Simplification of –ping and –ping-restart. Checks the current connection state by ICMP PING. Settings are ``. | `5 30` | ✔ | | **(user)** Change the user ID of the OpenVPN process after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. This is option only included in the `xx-region-x-client.conf` file for Linux operating systems. | `root` | ✔ | | **(group)** Optional group to be owner of this tunnel. This is option only included in the `xx-region-x-client.conf` file for Linux operating systems. | `nogroup` | ✔ | | **persist-key** Don't re-read key files across SIGUSR1 or --ping-restart. | | ❌ | | **persist-tun** Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts. | | ❌ | | **remote-cert-tls** Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. | `server` | ❌ | | **verb** Set output verbosity. Level 3 is recommended if you want a good summary of what’s happening without being swamped by output. | `3` | ✔ | | **auth-nocache** VPN client will not cache the username and password needed for authentication in virtual memory. This will prevent the log entry "WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this" upon connection establishment. | | ✔ | | **auth-user-pass** Authenticate with server using username/password from a file containing username/password on 2 lines. | ` /etc/openvpn/credentials.txt` | ✔ | | **auth-retry** Controls how OpenVPN responds to username/password verification errors such as the client-side response to an AUTH_FAILED message from the server or verification failure of the private key password. | `nointeract` | ✔ | | **tun-mtu** Optional parameter Maximum Transmission Units. In most cases, leave this parameter set to its default value. In case of issues with HTTPS or SSH connections, try lowering this value. | `1500` | ✔ | | **certificates** Certificates included in the config file. | | ❌ | More information about the configuration options can be found in the OpenVPN Reference Manual. Password Cache Warning If detailed logging is setup for the OpenVPN client, the following warning might appear when the OpenVPN client is started: _WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this._ This warning can be avoided by adding the `auth-nocache` parameter into the OpenVPN client configuration file. This should usually have no side affects, nevertheless the [official documentation](https://community.openvpn.net) states: “If specified, this directive will cause OpenVPN to immediately forget username/password inputs after they are used. As a result, when OpenVPN needs a username/password, it will prompt for input from `stdin`, which may be multiple times during the duration of an OpenVPN session.“ VPN Credential File The `credentials.txt` file downloaded from the CMP (see extract below) contains a user id as username and an access token as password for the 1NCE VPN server. The content of this file does not need to be modified. The location of this file needs to be set in the VPN Config File `xx-region-x-client.ovpn`. ```text credentials.txt ``` --- # VPN Setup Source: https://help.1nce.com/docs/network-services/network-services-vpn-service/vpn-service-setup-guides/ --- # UBIRCH - SIM Blockchain Source: https://help.1nce.com/docs/platform-services/platform-services-blockchain/ Together with UBIRCH, we have boosted our 1NCE IoT Flat Rate by adding a blockchain security component to our IoT FlexSIM card to combine high quality IoT connectivity with blockchain-based IoT security. The outcome is the Blockchain on a SIM solution. The following sections of the guide will provide an overview of the features and implementation offered by the UBIRCH Blockchain solution. # Functional Description The SIM application client provides signature and chaining services to seal original data, generated on embedded devices through the SIM card. It takes care of packaging the hashed data and signing the package into the UBIRCH PROTOCOL PACKET (UPP) . Sending the UPP to the UBIRCH backend must be handled by the customer application. At the backend the anchoring in the blockchain is performed. The backend can also be used to verify already anchored UPPs.\ The original data must be stored in a customer database to be able to execute verification requests at a later stage. UBIRCH does not store any original sensitive data! If the SIM Card is used together with the UBIRCH test kit, the sensor data is sent to the UBIRCH Simple Data Service, which stores the data. It is an example for a data service to be implemented by the customer. UPP data is sent to the SIM application via SIM APDU commands. The data encoding and handling of AT commands is done by the library code. Each SIM card comes pre-provisioned with a UUID Universally Unique Identifier) and a cryptographic key pair that is registered with the UBIRCH backend system and just needs to be claimed using the IMSI of the SIM at the [UBIRCH console] ([https://id.prod.ubirch.com/auth/realms/ubirch-2.0/protocol/openid-connect/auth?scope=openid\&state=GlFTOMMdHcg\_W0VRWmF29PUJtci8AuGQOyYonO\_KoJk.Qq9x8PTUuaw.ubirch-2.0-user-access\&response\_type=code\&client\_id=ubirch-default-realm-connector\&redirect\_uri=https%3A%2F%2Fid.prod.ubirch.com%2Fauth%2Frealms%2Fubirch-default-realm%2Fbroker%2Fubirch-2.0-centralised-user-auth%2Fendpoint\&nonce=175f1067-d429-4f56-8f97-2708f500f39a](https://id.prod.ubirch.com/auth/realms/ubirch-2.0/protocol/openid-connect/auth?scope=openid\&state=GlFTOMMdHcg_W0VRWmF29PUJtci8AuGQOyYonO_KoJk.Qq9x8PTUuaw.ubirch-2.0-user-access\&response_type=code\&client_id=ubirch-default-realm-connector\&redirect_uri=https%3A%2F%2Fid.prod.ubirch.com%2Fauth%2Frealms%2Fubirch-default-realm%2Fbroker%2Fubirch-2.0-centralised-user-auth%2Fendpoint\&nonce=175f1067-d429-4f56-8f97-2708f500f39a)). To claim the SIM and start working with the SIM Application, simply follow the steps in [Setup](https://github.com/ubirch/ubirch-testkit#set-up-sim-card-and-device) SIM card and device . If you still cannot manage to setup your device, please also check the UBIRCH FAQs and if this does not help, [Contact UBIRCH](https://ubirch.com/contact). ![ubirch_application.PNG](/img/platform-services/platform-services-blockchain/926474a-ubirch_application.PNG) # UBIRCH TRUST SERVICE The UBIRCH Trust Service is a fast cloud-based backend responsible for identity management, blockchain anchoring, device and account management. It offers simple to use REST API endpoints to anchor incoming UPPs and to verify received data. ![ubirch_trust_chain.PNG](/img/platform-services/platform-services-blockchain/5d72f62-ubirch_trust_chain.PNG) To improve performance, scalability and to keep transaction cost manageable, the UBIRCH Trust Service creates its own merkle-tree structure, aggregating incoming UPPs into larger root-hashes, which get anchored into a blockchain every minute. The Trust Service is built as a Kubernetes cluster being hosted on Microsoft AZURE. All performance-critical components can equally be deployed on-premise, should the necessity arise. It is optimized for very high throughput. # Sealing & Verifying Process The following two sections will shortly describe the two most important processes of sealing and verifying data. In general the process always consists of: 1. Seal data at the point of its 'birth' with the UPP. 2. Anchor the UPP into the blockchain. 3. Verify received data against its UPP in the blockchain. ## Seal and Anchor Data The following simplified sequence diagram uses pseudo code to show the process of sealing and anchoring data. This example shows the usage of an application which is sharing data /measurements, test results) with any kind of data receiver. This is just an example to show the process and not necessarily the exact final architecture to use UBIRCH. ![ubirch_data_sealing.PNG](/img/platform-services/platform-services-blockchain/4bfb4be-ubirch_data_sealing.PNG) 1. The customer device creates data. 2. The customer device hashes the data, as a unique digital fingerprint. 3. The customer device sends the hash to the UBIRCH NANO client on a SIM, where a signed UPP is created. 4. The customer device sends the data to the customer application for storage and further processing. 5. The customer device sends the UPP to the UBIRCH TRUST SERVICE. 6. The UBIRCH TRUST SERVICE verifies the origin of the UPP by checking the signature. 7. The UBIRCH TRUST SERVICE aggregates the UPP. 8. The UBIRCH TRUST SERVICE anchors the UPP in the public blockchain. ## Verify Data Each received data packet which has been sealed with the UBIRCH CLIENT (has been ubirched) at the place of its 'birth', can easily be verified by the receiver, regarding its authenticity, integrity and chain validity. Since the seal is not directly attached to the data and anchored to the blockchain, the verification can be done by anyone, who has (access to) the data. This process is completely independent from the channel of transmission, which has been used to share the data and is also beyond any system boundaries.\ The following simplified sequence diagram uses pseudo code to show the process of verifying UBIRCHed data (HASH-method). ![ubirch_data_verification.PNG](/img/platform-services/platform-services-blockchain/5bad503-ubirch_data_verification.PNG) 1. The customer application acquires the data to verify. 2. The customer application recreates the hash of the data, like it was created on the device (before creating the original UPP). 3. The customer application sends this hash to the verification endpoint of the UBIRCH TRUST SERVICE. 4. The UBIRCH TRUST SERVICE looks up the original UPP, based on the incoming hash. 5. The UBIRCH TRUST SERVICE checks the signature of the found UPP. 6. The UBIRCH TRUST SERVICE looks up the blockchain transaction, which contained the according UPP. 7. The UBIRCH TRUST SERVICE returns OK (or NOK) and all the proofs needed to cryptographically reproduce the validation result. # Libraries & Implementation The UBIRCH client is provided as a SIM application (SIGNiT) and additional library code that handles the communication between customer code and the SIM card application. The library code is provided as open source. A hardware test kit based on [Pycom](https://pycom.io/) modules is available.\ Library Source Repository: [https://github.com/ubirch/ubirch-protocol-sim](https://github.com/ubirch/ubirch-protocol-sim)\ TestKit Source Repository: [https://github.com/ubirch/ubirch-testkit](https://github.com/ubirch/ubirch-testkit) ## Requirements * A system with access to a modem that supports AT+CSIM commands. * Alternatively a ubirch test kit. ## Security Considerations The SIM application is protected by a unique PIN. The example test kit code handles retrieving the PIN from the UBIRCH backend. Developers should consider storing this PIN securely on the device, as it is the key to cryptographic functionality provided by the SIM application. # Support & Contact Need help with the UBIRCH Blockchain? Feel free to reach out to the [Ubirch Helpdesk](https://ubirch.atlassian.net/servicedesk/customer/portal/1) --- # Data Streamer Service Source: https://help.1nce.com/docs/platform-services/platform-services-data-streamer/
![Schematic diagram of the Data Streamer Service structure.](/img/platform-services/platform-services-data-streamer/001.png)
Access to the SIM status, events, and usage data is a key factor when it comes to monitoring and debugging IoT-focused systems. This type of data could be queried from the 1NCE API, but this generates a lot of undesired overhead traffic and load. The ideal solution for getting 1NCE SIM-related event and usage data as a stream is the 1NCE Data Streamer Service. The Data Streamer Service allows subscribing to real-time Event and Usage Records for all SIM cards. Incoming information is pushed directly to a customer-specified server endpoint with the Rest API integration or an already integrated cloud service such as AWS S3, Kinesis, DataDog, Keen.io, etc. For more details about this service, refer to the subchapters in the menu on the left side. In this chapter of the Developer Hub Guide, the Features of the Data Streamer, as well as the Setup possibilities and an overview of the Event and Usage Records are shown. --- # Event Records Source: https://help.1nce.com/docs/platform-services/platform-services-data-streamer/data-streamer-event-records/ The 1NCE Data Streamer Service offers a stream of Event and Usage Records. This chapter will focus on the Event Record specification. The exact format of the events is dependent on the used integration. In this chapter, the focus lies on the JSON Object format. Please note that empty, nested JSON objects are listed as NULL objects. For other integrations the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used. The following sections will cover the individual parts of the Event Record JSON: * [Generic Properties](#generic-properties) * [Additional Properties](#additional-properties) * [Detail Properties](#detail-properties) * [PDP Context Object](#pdp-context-object) *** ## Example Event Records Let us start with a few Example Event Records in the form of JSON Objects from the Data Streamer. Listed below in the different tabs are some example Event Records for different Event Types. All Examples are in the JSON Format just like it would be delivered by the Data Streamer with the custom HTTP endpoint method. Please note that some fields only include placeholder or example values. Furthermore, some of the fields might be dependent on the used Radio Access Technology and other variables.
01_Update_Location ```json 01_Update_Location.json { "imsi": { "imsi": "", "id": 123456, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from VLR for IMSI='', now attached to VLR=''.", "alert": false, "id": 1234567890, "user": null, "detail": { "mnc": [ { "mnc": "20", "id": 327 }, { "mnc": "16", "id": 328 } ], "tapcode": [ { "tapcode": "NLDDT", "id": 470 }, { "tapcode": "NLDPN", "id": 471 } ], "name": "T-Mobile", "country": { "iso_code": "nl", "country_code": "31", "name": "Netherlands", "id": 141, "mcc": "204" }, "id": 730 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 1, "description": "Update location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
02_Update_GPRS_Location ```json 02_Update_GPRS_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from SGSN for IMSI='', now attached to SGSN='', IP='', RAT type='E_UTRAN'.", "alert": false, "id": 1234567, "user": null, "detail": { "mnc": [ { "mnc": "01", "id": 2 } ], "tapcode": [ { "tapcode": "DEUD1", "id": 1 }, { "tapcode": "DEUK9", "id": 851 } ], "name": "T-Mobile", "country": { "iso_code": "de", "country_code": "49", "name": "Germany", "id": 74, "mcc": "262" }, "id": 2 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456789 }, "event_type": { "id": 2, "description": "Update GPRS location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
03_Create_PDP_Context ```json 03_Create_PDP_Context { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New PDP Context successfully activated with SGSN CP=, DP=.", "alert": false, "id": 1234567890, "user": null, "detail": { "pdp_context": { "tx_teid_control_plane": 3162410000, "sgsn_control_plane_ip_address": "", "sac": null, "ratezone_id": "2171", "rat_type": 2, "tunnel_created": "2021-08-09T12:00:27", "breakout_ip": "unavailable", "tariff_id": "442", "mnc": "01", "apn": "iot.1nce.net", "ue_ip_address": "", "gtp_version": 1, "rac": null, "region": "eu-central-1", "tx_teid_data_plane": 2014413000, "ggsn_data_plane_ip_address": "", "ci": 5559, "tariff_profile_id": "129000", "pdp_context_id": 110753000, "imsi": "901405100000000", "operator_id": "2", "mcc": "262", "imeisv": "863576047850000", "sgsn_data_plane_ip_address": "", "ggsn_control_plane_ip_address": "", "lac": 38701, "nsapi": 5, "rx_teid": 110750000 }, "name": "T-Mobile", "id": 2, "country": { "mcc": "262", "iso_code": "de", "name": "Germany", "id": 74, "country_code": "49" } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 3, "description": "Create PDP Context" }, "timestamp": "2019-01-21T09:36:17Z" } ```
05_Delete_PDP_Context ```json 05_Delete_PDP_Context.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "PDP Context deleted.", "alert": false, "id": 12345678000, "user": null, "detail": { "pdp_context": { "tx_teid_control_plane": 3162419000, "sgsn_control_plane_ip_address": "", "sac": null, "rat_type": 2, "tunnel_created": "2021-08-09T12:00:27", "breakout_ip": null, "mnc": "01", "apn": null, "ue_ip_address": "", "gtp_version": 1, "rac": null, "region": "eu-central-1", "tx_teid_data_plane": 2014410000, "ggsn_data_plane_ip_address": "", "ci": 5500, "pdp_context_id": 110753000, "imsi": "901405100000000", "mcc": "262", "imeisv": "8635760478506578", "sgsn_data_plane_ip_address": "", "ggsn_control_plane_ip_address": "", "lac": 38700, "nsapi": 5, "rx_teid": 110753000 }, "name": "T-Mobile", "id": 2, "volume": { "rx": 0, "tx": 0, "total": 0 }, "country": { "mcc": "262", "iso_code": "de", "name": "Germany", "id": 74, "country_code": "49" } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 5, "description": "Delete PDP Context" }, "timestamp": "2019-01-21T09:36:17Z" } ```
09_SIM_Suspension ```json 09_SIM_Suspension.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "Status of SIM changed from 'Activated' to 'Suspended'", "alert": false, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456 }, "event_type": { "id": 9, "description": "SIM suspension" }, "timestamp": "2019-01-21T09:36:17Z" } ```
08_SIM_Activation ```json 08_SIM_Activation.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2019-01-21T09:36:17Z" }, "description": "Status of SIM changed from 'Suspended' to 'Activated'", "alert": false, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": null, "id": 123456 }, "event_type": { "id": 8, "description": "SIM activation" }, "timestamp": "2019-01-21T09:36:17Z" } ```
16_Purge_GPRS_Location ```json 16_Purge_GPRS_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SGSN location information has been purged for IMSI=''.", "alert": false, "id": 12345678, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 16, "description": "Purge GPRS location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
15_Purge_Location ```json 15_Purge_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "VLR location information has been purged for IMSI=''.", "alert": false, "id": 12345678, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456 }, "event_type": { "id": 15, "description": "Purge location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
18_Data_Quota_Threshold_Reached ```json 18_Threshold_Reached.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "Endpoint quota threshold reached, volume is below 20%.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "threshold_volume": 118.983794, "volume": 118.968383, "threshold_percentage": 20 } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 18, "description": "Quota threshold reached" }, "timestamp": "2019-01-21T09:36:17Z" } ```
19_Data_Quota_Used_Up ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Quota volume is completely used up and data access denied for endpoint.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "threshold_volume": 100, "volume": "0.015085", "threshold_percentage": 20 } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 19, "description": "Quota used up" }, "timestamp": "2019-01-21T09:36:17Z" } ```
20_SMS_Threshold_Reached ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota threshold reached, volume is below 20%.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "volume": 0, "threshold_percentage": 20, "threshold_volume": 1, "traffic_type": { "id": 6, "description": "SMS" } } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 20, "description": "SMS quota threshold reached" }, "timestamp": "2019-01-21T09:36:17Z" } ```
21_SMS_Quota_Used_Up ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota volume is completely used up and SMS access denied for endpoint.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "volume": 1, "threshold_percentage": 20, "threshold_volume": 1, "traffic_type": { "id": 6, "description": "SMS" } } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 21, "description": "SMS quota used up" }, "timestamp": "2019-01-21T09:36:17Z" } ```
52_Data_Quota_Enabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "Data quota management got enabled for service profile (id = 123123 - Generic with Quota or Limits), endpoints of this service profile without an active data quota will be throttled or blocked from data service.", "id": 1234567890, "event_type": { "id": 52, "description": "Data quota enabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
53_Data_Quota_Disabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "Data quota management got disabled for the service profile (id = 123123 - Generic with Quota or Limits).", "id": 1234567890, "event_type": { "id": 53, "description": "Data quota disabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
54_SMS_Quota_Enabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "SMS quota management got enabled for service profile (id = 123123 - Generic with Quota or Limits), endpoints of this service profile without an active SMS quota will be blocked from SMS service.", "id": 1234567890, "event_type": { "id": 54, "description": "SMS quota enabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
55_SMS_Quota_Disabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "SMS quota management got disabled for the service profile (id = 123123 - Generic with Quota or Limits).", "id": 1234567890, "event_type": { "id": 55, "description": "SMS quota disabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
56_Data_Quota_Assigned ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Data quota got assigned with volume of 500.000000 MB. On exhaustion, the data service will be blocked.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 56, "description": "Data quota assigned" }, "detail": "{\"endpoint_quota_id\":123123, \"quota_status_id\": 1,\"action_on_quota_exhaustion_id\": 1,\"volume\": 500.000000, \"expiry_date\": 2022-03-31T00:00:00Z, \"peak_throughput\": 128000,\"last_volume_added\": 500.000000,\"last_status_change_date\": 2022-03-24T12:46:27Z, \"auto_refill\": true,\"threshold_percentage\": 20,\"threshold_volume\": 100.000000}", "timestamp": "2019-01-21T09:36:17Z" } ```
57_Data_Quota_Deleted ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Data quota got deleted and data service will be blocked for this endpoint until new data quota got assigned.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 57, "description": "Data quota deleted" }, "timestamp": "2019-01-21T09:36:17Z" } ```
58_SMS_Quota_Assigned ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota got assigned with volume of 250 SMS. On exhaustion, the SMS service will be blocked.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 58, "description": "SMS quota assigned" }, "detail": "{\"endpoint_quota_id\":123123, \"quota_status_id\": 1,\"action_on_quota_exhaustion_id\": 1,\"volume\": 500.000000, \"expiry_date\": 2022-03-31T00:00:00Z, \"peak_throughput\": 128000,\"last_volume_added\": 500.000000,\"last_status_change_date\": 2022-03-24T12:46:27Z, \"auto_refill\": true,\"threshold_percentage\": 20,\"threshold_volume\": 100.000000}", "timestamp": "2019-01-21T09:36:17Z" } ```
59_SMS_Quota_Deleted ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota got deleted and SMS service will be blocked for this endpoint until new SMS quota got assigned.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 59, "description": "SMS quota deleted" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_SMS_Forwarder ```json 00_SMS_Forwarder.json { "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": null, "imsi": null, "detail": null, "description": "Unable to dispatch DLR to API Callback URL '' (HTTP code=400), please verify the URL is correct and the application server is accepting requests.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_Disabled_Endpoint ```json 00_Disabled_Endpoint.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2019-01-21T09:36:17Z" }, "description": "Disconnecting data access for endpoint, because it has been disabled.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_SMS_API ```json 00_SMS_API.json { "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS to cannot be forwarded, because no API Callback URL defined in service profile.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
*** ## Generic Properties Generic Properties are fields that are always included in an Event Record JSON message received via the Data Streamer. The following table will list all these properties, their data type, and a short description. | Property | Data Type | Description | | :--------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | LONG (64 bit) | Unique ID for each Event Record sent. Duplicate received event IDs indicate possible retransmissions. | | `timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the event occurrence in the ISO 8601 format. | | `event_type` | JSON Object | Object with an id and a description about the occurred event. See [Event Types](#event-types) for a list of all possible values. | | `event_severity` | JSON Object | JSON object with an id and a description about the severity of the event. See [Event Severity](#event-severity) for a list of all possible values. | | `event_source` | JSON Object | An id and a description about the source of the event. See [Event Source](#event-source) for a list of all possible values. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Event Organization](#event-organization) for more information. | | `alert` | BOOLEAN | Events with a high impact on connectivity operation are flagged as an Alert. | | `description` | STRING | String with a human readable description of the event. | ### Event Types The different types of events are indicated by the Event Type nested object. This object contains an ID and a short description of the event. The following table lists all possible Event Types that can be received via the Data Streamer. | Event ID | Description | | :------- | :-------------------------------- | | 0 | Generic | | 1 | Update location | | 2 | Update GPRS location | | 3 | Create PDP Context | | 4 | Update PDP Context | | 5 | Delete PDP Context | | 6 | User authentication failed | | 7 | Application authentication failed | | 8 | SIM activation | | 9 | SIM suspension | | 10 | SIM deletion | | 11 | Endpoint blocked | | 12 | Organization blocked | | 13 | Support Access | | 14 | Multi-factor Authentication | | 15 | Purge Location | | 16 | Purge GPRS location | | 17 | Self-Signup | | 18 | Data Quota Threshold reached | | 19 | Data Quota used up | | 20 | SMS Quota Threshold reached | | 21 | SMS Quota used up | | 30 | OpenVPN authentication | | 50 | SIM Released | | 51 | SIM Assigned | | 52 | Data Quota Enabled | | 53 | Data Quota Disabled | | 54 | SMS Quota Enabled | | 55 | SMS Quota Disabled | | 56 | Data Quota Assigned | | 57 | Data Quota Deleted | | 58 | SMS Quota Assigned | | 59 | SMS Quota Deleted | | 60 | Data Quota expired | ### Event Severity The severity levels of an event indicate what impact the event has on the correct operation of the system. The possible Event Severity values are listed below: | Severity ID | Description | | :---------- | :---------- | | 0 | INFO | | 1 | WARNING | | 2 | CRITICAL | ### Event Source Based on the Event Type, a different originating Event Source might be responsible for triggering the event. The possible sources consisting of an ID and a Description are listed below. | ID | Description | | :- | :------------- | | 0 | Network | | 1 | Policy Control | | 2 | API | ### Event Organization Each Event Record includes information about the originating organization. This helps to identify the organization in the use case of multiple Data Streamer for sub organizations. The JSON property fields of this object are listed below. | Property | Data Type | Description | | :------- | :-------- | :----------------------------- | | `id` | INTEGER | Unique ID of the organization. | | `name` | STRING | 1NCE Customer ID. | *** ## Additional Properties Event Records that directly relate to SIMs, Endpoints, or Users might include some of the following optional properties. | Property | Data Type | Description | | :--------- | :---------- | :------------------------------------------------------------------------------------------------ | | `imsi` | JSON Object | International Mobile Subscriber Identity, see [IMSI Object](#imsi-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM Object](#sim-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint Object](#endpoint-object) for more information. | ### IMSI Object The International Mobile Subscriber Identity is used to identify each device with a SIM. The following parameters are included in an Event Record. | Property | Data Type | Description | | :------------ | :-------------- | :-------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the IMSI. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | | `import_date` | TIMESTAMP (UTC) | Timestamp when the IMSI was provisioned in the ISO 8601 format. | ### SIM Object Each SIM card has unique properties and parameters. This data is included in the event stream. A list of the available data fields is shown below. | Property | Data Type | Description | | :---------------- | :-------------- | :---------------------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | | `production_date` | TIMESTAMP (UTC) | Timestamp when the SIM was produced in the ISO 8601 format. | ### Endpoint Object As a SIM is placed inside a device, some information about this endpoint is transferred via the mobile network. This information is useful to identify the specific device type and certain connection parameters. A list of all Endpoint Objects is listed below. | Property | Data Type | Description | | :----------- | :-------- | :--------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the Endpoint. | | `name` | STRING | Name of the Endpoint configuration. | | `ip_address` | STRING | Specific static IP Address of the SIM card/Endpoint. | | `tags` | STRING | Any Tags assigned to the Endpoint. | | `imei` | STRING | International mobile equipment identity of the Endpoint/Device with the SIM. | *** ## Detail Properties For certain Event Types, additional information parameters are added in the Detail Properties. A list of the object parameters and fields is listed below. | Property | Data Type | Description | | :------------ | :---------- | :------------------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID for the used mobile network operator. | | `name` | STRING | Name of the mobile network operator. | | `country` | JSON Object | Country of the mobile network operator. See [Country Object](#country-object) for more information. | | `pdp_context` | JSON Object | Object with details about the PDP Context. See [PDP Context Object](#pdp-context-object) for more information. | | `volume` | JSON Object | Object with details about the Volume used. See [Volume Object](#volume-object) for more information. | ### Country Object A nested JSON object inside the Detail Properties contains more information about the country where the SIM event took place. The fields of the Country JSON are listed below. | Property | Data Type | Description | | :---------------------- | :-------- | :------------------------ | | `country.id ` | INTEGER | Unique ID of a country. | | `country.name ` | STRING | Name of the country. | | `country.country_code ` | STRING | Country Code | | `country.mcc` | STRING | Mobile Country Code (MCC) | | `country.iso_code ` | STRING | ISO Country Code | ### PDP Context Object An Event Record for a PDP Context includes a wide range of additional information in the Detail Properties. The individual fields are listed below. | Property | Data Type | Description | | --- | --- | --- | | `pdp_context_id` | INTEGER | ID of the PDP Context. | | `tunnel_created` | TIMESTAMP (UTC) | Creation time of the PDP Session. | | `gtp_version` | STRING | GTP Version 1/2 | | `ggsn_control_plane_ip_address ` | STRING | IP Address of GGSN/PGW Control Plane | | `ggsn_data_plane_ip_address` | STRING | IP Address of GGSN/PGW Data Plane | | `sgsn_control_plane_ip_address` | STRING | IP Address of SGSN/SGW Control Plane | | `sgsn_data_plane_ip_address` | STRING | IP Address of SGSN/SGW Data Plane | | `region` | STRING | Region of the Data Plane. | | `breakout_ip` | STRING | IP Address used for the Internet Breakout. | | `apn` | STRING | Access Point Name (APN) | | `nsapi` | INTEGER | Network Service Access Point Identifier (NSAPI) | | `ue_ip_address ` | STRING | IP address of the device. | | `imeisv` | STRING | International Mobile Equipment Identity - Softwareversion | | `mcc` | STRING | Mobile Country Code (MCC) | | `mnc` | STRING | Mobile Network Code (MNC) | | `lac` | INTEGER | Location Area Code (LAC) | | `sac` | INTEGER | Service Area code (SAC) | | `rac` | INTEGER | Routing Area code (RAC) | | `ci` | INTEGER | Cell Identification (CI) | | `rat_type` | INTEGER | Radio Access Type (RAT) 1 - 3G 2 - 2G 5 - HSPA+ 6 - LTE\* 8 - NB-IoT 9 - CAT-M\* | \* Only from some mobile operators *rat\_type* 9 is sent for CAT-M connections (depends on the 3GPP Release in their Core Network). For the majority of the CAT-M connections the rat\_type in the data streamer is 6, since CAT-M is based on the 4G standard. ### Volume Object With each PDP Context, some information about the Data Usage is included in the Volume JSON. The content description of the fields is listed below. | Property | Data Type | Description | | :------------- | :------------ | :------------------------------ | | `volume.rx` | DECIMAL(14,6) | Downstream Volume in MegaBytes. | | `volume.tx` | DECIMAL(14,6) | Upstream Volume in MegaBytes. | | `volume.total` | DECIMAL(14,6) | Total Volume Usage. | --- # Features & Limitations Source: https://help.1nce.com/docs/platform-services/platform-services-data-streamer/data-streamer-features-limitations/ # Features ## Event and Usage Monitoring With the 1NCE Data Streamer Service, customers can get live-streamed Event and Usage Records for their 1NCE SIM cards. This allows 1NCE customers to monitor the current connectivity status of each SIM individually in near real-time. The Usage Records provide additional insight into the data and SMS volume usage patterns of the connected IoT devices. The data streamer helps 1NCE customers to keep an eye on the IoT connectivity of their devices with a 1NCE SIM card. ## Multi-Target Streaming The 1NCE Data Streamer Service allows configuring multiple target applications for the same streamed data. This allows the customer to integrate both the Event and Usage Records into multiple data analytics and monitoring systems at once. Each configured receiver will get the latest updates pushed. The individual streams can be configured in the 1NCE Portal under the Configuration Tab. In the Portal, individual data streams can also be paused/resumed, and deleted. ## Data Analytics Platforms The usage and event stream can be integrated into the most commonly used platforms for data analytics and monitoring. 1NCE provides ready to use integrations for some selected 3rd party platforms. Currently the 1NCE Data Streamer supports the following integrations options: * Keen.io * DataDog * AWS S3 * AWS Kinesis ## Custom API Endpoint In addition to the ready to use 3rd party integrations, 1NCE offers the possibility to integrate an own HTTP Post Endpoint which can be configured to receive the records from the data streamer. Customers can use this integration to include the 1NCE Data Streamer Service into their application or monitoring system of choice. *** # Limitations ## DataDog Integration The DataDog integration only provides Data Volume monitoring capabilities. That means only Data Volume in Bytes is reported, and SMS consumption cannot be monitored. --- # Setup Guides Source: https://help.1nce.com/docs/platform-services/platform-services-data-streamer/data-streamer-setup-guides/ In this chapter, the setup of the 1NCE Data Streamer Service for different cloud integrations will be shown in detail. The 1NCE Data Streamer Service offers the following integrations:
![](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/d47972b-rest_api.svg)
Click on one of the icons to get to the setup guide for the selected integration. *** # General Setup Information ## Stream Types When configuring the 1NCE Data Streamer Service, different Stream Types are selectable. The options can be configured for each Data Streamer setup. It can be selected between either Usage Data or Event Data. A combined stream of Usage and Event Data is not supported and can therefore not be selected in the management portal. ## Warnings & Errors In the case that there was an error with Data Streamer connection, a warning record with respective error code is shown in the Data Streamer configuration. In this case, please verify that the service is reachable and is set up correctly. The streamer service uses a back off systems design that retries sending data to the desired destination in case of an failure. Please note that after a certain retry count the streamer goes into FAILED state. If the streamer is in the error state, please try to restart or recreate the stream integration in the 1NCE Portal. ## Stream Management With the 1NCE Data Streamer, it is possible to set up multiple streams with different destinations at once. Each new connection can be configured independently of the others in the 1NCE Portal. A connection can be paused/started or deleted independently of the other setups. To change the configuration of a stream, the old stream has to be deleted and a new stream needs to be set up. Please note that the pausing/starting and creation of a stream can take a few seconds to become active. *** # REST API - Integration The REST API connection to the Data Streamer is ideal for custom server application integrations. This method offers the most flexible, custom integration of the Data Streamer Service into existing analytics, reporting, and monitoring pipelines. The REST API supports both Event and Usage Records.\ The customer server needs to provide an HTTP POST endpoint (see [Endpoint URL](#endpoint-url)). The 1NCE Data Streamer posts a list of events as they occur towards this endpoint.\ As of Version 2.0 of the Data Streamer, events are always provided in BULK mode. Therefore, a list of JSON Event or Usage Record is delivered to the given Endpoint. Using Bulk mode, each HTTP POST will include an array of objects. The maximum amount of records per sent request is 3000 JSON objects in a list. The POST requests are sent at intervals. The endpoint consumes the HTTP POST by sending the HTTP 200 Code as a response to the incoming request. The Data Streamer does not respond to HTTP redirect codes (3xx).\ The HTTP integration uses a retry mechanism with a backoff policy. After a given time, the Data Streamer will go into FAILED state and stop delivering events. After the potential error in the HTTP endpoint behavior has been resolved by the customer, the Data Streamer needs to be restarted by the customer. In the Connectivity Management Platform (CMP), a Basic Authentication Header needs to be set when configuring the REST API integration. This header is of the Base64 format consisting of the `username:password`. The server application endpoint can implement the Basic Authentication Method and only accept incoming requests with the correct header. This offers enhanced security and protection against any requests that do not originate from the 1NCE Data Streamer Service.\ For **testing purposes only**, the Basic Authentication Header value can be set to an arbitrary string and the processing on the server-side can be ignored. We strongly recommend doing this only for **TESTING**. In a production environment, we suggest **ALWAYS** implementing the Basic Authentication Method. ## Endpoint URL The endpoint URL for the Data Streamer in the CMP needs to be valid. URL with public IP addresses (`https://://`) are not supported. Custom ports for the endpoint can be configured via the URL (`https://://`). ## Certificates The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using [Let's Encrypt](https://letsencrypt.org/de/) certificates. ## Endpoint Capacity Be aware that the REST API integration will deliver the incoming events as a list of JSON objects. Dependent on the amount of SIMs and occurred records this request can be quite large. A maximum limit of 3000 records per request is set. 1NCE customers with a large quantity of SIMs and high number of events as such must be aware that their backend system receiving data from the stream needs to have the capacity to handle large incoming requests. *** # Keen.io - Integration The Keen.io platform is a managed event streaming platform used for streaming, analyzing, and embedding rich data. The 1NCE Data Streamer Service can easily be integrated with this service. The Keen.io integration supports both Event and Usage Records. The following items are required for the setup process with Keen.io: * Keen.io Account * New Keen.io Project * Project ID Key * Write Key of the Project * Collection Name In the 1NCE Connectivity Management Platform (CMP), select the desired Stream Type and Keen.io as API Type. Enter the Product ID key and the Write Key of the created Keen.io project. Further the Collection Name is needed to indicate where to stream the data to.\ After the Data Stream integration was created, the first data will be arriving at Keen.io. The incoming data can be seen on the streams tab. *** # DataDog - Integration DataDog is a cloud monitoring service that can be used to monitor the endpoint volume of the 1NCE SIM cards using custom dashboards and trigger events. Please ensure that the region of the used DataDog account matches with the Data Streamer setup fields. To create a DataDog integration, the following is required: * DataDog Account * API Integration * API Key * DataDog Account Region For the configuration of the DataDog Data Streamer integration enter the API Key and the account Region in the Connectivity Management Platform configuration. After the stream was created, data will be transferred to DataDog. In the DataDog explorer, the incoming data can be monitored. The following metrics can be viewed in DataDog: endpoint.volume, endpoint.volume\_tx, endpoint.volume\_rx, and endpoint.cost. When selecting the Stream Type, please note that Event Records are currently not available in DataDog. *** # AWS - Integrations The 1NCE Data Streamer Service can be integrated with both AWS S3 and AWS Kinesis. AWS Kinesis is ideal for collecting and processing large streamed data records in real-time. AWS S3 is an object-based storage solution. The Data Streamer can push CSV files into a S3 bucket allowing for easy, largescale data collection and further processing later on by related AWS Services.\ Both AWS S3 and Kinesis are integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the Connectivity Management Portal (CMP). ## S3 - Integration The S3 integration will provide the Event or Usage Records through an S3 bucket where they are uploaded as CSV files. The CSV filenames for events are `events_YYYYMMDD_HHmmss.csv` and `cdr_YYYYMMDD_HHmmss.csv` for usage records. Each file contains a collection records over a small period. A sample for an event record file type is provided below. ```text cdr_20210512_070123.csv "id","event_start_timestamp","event_stop_timestamp","organisation_id","organisation_name","endpoint_id","sim_id","iccid","imsi","operator_id","operator_name","country_id","operator_country_name","traffic_type_id","traffic_type_description","volume","volume_tx","volume_rx","cost","currency_id","currency_code","currency_symbol","ratezone_tariff_id","ratezone_tariff_name","ratezone_id","ratezone_name","endpoint_name","endpoint_ip_address","endpoint_tags","endpoint_imei","msisdn_msisdn","sim_production_date","operator_mncs","country_mcc" "4427264xxx","2021-05-11 11:17:25","2021-05-11 11:19:51","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.000741","0.000395","0.000346","0.0007410000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" "4427320xxx","2021-05-11 11:17:29","2021-05-11 11:24:56","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.003210","0.001803","0.001407","0.0032100000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" ``` ## Cloud Formation Setup The easiest setup for the stream integration into AWS S3 is by using the Cloud Formation Template via the 1NCE Connectivity Management Portal (CMP). As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. **1.** Open the CMP and navigate to *Configuration>Data Streams>Add New Data Stream*.\ **2.** In the popup select AWS S3 as *API Type* and select the desired *Stream Type*.\ **3.** Click on *Create IAM Role* (see Figure below) to open the Cloud Formation Template in a separate window. ![cmp_popup_ds.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/2c56973-cmp_popup_ds.png) **4.** Adapt the CFN Template parameters (Stack Name, S3BucketName). Do NOT change AllowedExternalID and DatastreamerRoleARN.\ **5.** Set the *IAM Creation* checkbox.\ **6.** Execute the CFN Stack by clicking on *Create Stack*. ![cfn_s3_template.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/0138a7e-cfn_s3_template.png) **7.** Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![cfn_complete.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/a394239-cfn_complete.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_s3_cfn_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/67ecf11-aws_s3_cfn_cmp.png) After completing the steps, the selected record type should show up in the AWS S3 bucket. If there are any issues or problems with the setup, please feel free to contact our support. ## Kinesis - Integration With the Kinesis integration, Event and Usage Records from the 1NCE Data Streamer are directed to AWS Kinesis for real-time data analytics. ### Cloud Formation Setup - Kinesis To setup the 1NCE Data Streamer integration with AWS Kinesis, it is recommended to use the Cloud Formation Template provided in the 1NCE Connectivity Management Portal (CMP). As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. **1.** Open the CMP and navigate to *Configuration>Data Streams>Add New Data Stream*.\ **2.** In the popup select AWS Kinesis as *API Type* and select the desired *Stream Type*.\ **3.** Click on *Create IAM Role* to open the Cloud Formation Template in a separate window. ![aws_kinesis_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/7ae09fb-aws_kinesis_cmp.png) **4.** Adapt the CFN Template parameters (Stack Name, KinesisStreamName). Do NOT change AllowedExternalID and DatastreamerRoleARN.\ **5.** Set the *IAM Creation* checkbox.\ **6.** Execute the CFN Stack by clicking on *Create Stack*. ![aws_kinesis_cfn.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/d6f5e3a-aws_kinesis_cfn.png) **7.** Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/27f986f-aws_cfn_done.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_kinesis_cfn_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/4f535ec-aws_kinesis_cfn_cmp.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. After completing the steps, the selected record type should show up in the AWS Kinesis Stream bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. --- # Usage Records Source: https://help.1nce.com/docs/platform-services/platform-services-data-streamer/data-streamer-usage-records/ The 1NCE Data Streamer Service offers a stream of Event and Usage Records. This chapter will focus on the Usage Record specification. In this chapter, the focus lies on the JSON Object format. For other integrations, the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used. Usage Records are triggered on SIM level and are based on the following rules: - For an ongoing PDP data connection, at most, one record every 15 minutes if more than 100kB of data was used. This record contains the aggregated usage since the start of the PDP or since the last usage record. - One record on the closure a PDP data connection. This record contains the usage since the last record or the entire aggregated usage if no prior record has been provided for the closed PDP data connection. - For SMS a usage record is provided per individual MO-/MT-SMS send. In the following, the two types of Usage Records and the included data fields will be shown. The 1NCE Data Streamer provides two types of records for SMS and Data volume usage. *** ## Example Usage Records Let us start with a few Example Usage Records in the form of JSON Objects from the Data Streamer. Please note that some fields only include placeholder or example values.
05_Data_Usage_Record ```json 05_Data_Usage_Record.json { "imsi": "", "organisation": { "name": "8100xxxx", "id": 1234 }, "start_timestamp": "2021-08-09T12:59:05Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "id": 2, "name": "T-Mobile", "mnc": "01", "country": { "id": 74, "mcc": "262", "name": "Germany" } }, "tariff": { "ratezone": { "name": "Rate Zone 2 (EU - DE)", "id": 2067 }, "name": "1NCE Production 01", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "Data", "id": 5 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678, "balance": null }, "cost": 0.001176, "volume": { "total": 0.001176, "tx": 0.001176, "rx": 0.0 } } ```
06_SMS_Usage_Record ```json 06_SMS_Usage_Record.json { "imsi": "", "organisation": { "name": "8100xxxx", "id": 12345 }, "start_timestamp": "2021-08-09T12:51:20Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "mnc": "01", "name": "T-Mobile", "country": { "name": "Germany", "id": 74, "mcc": "262" }, "id": 5 }, "tariff": { "ratezone": { "name": "Zone 1", "id": 2067 }, "name": "Tariff 1", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "SMS", "id": 6 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "balance": null, "id": 1234567 }, "cost": 1.0, "volume": { "total": 1.0, "tx": 0.0, "rx": 1.0 } } ```
*** ## Usage Data Properties These are the main properties of a Usage Record that help to identify the endpoint and provide an insight into the volume used. | Property | Data Type | Description | | :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------ | | `id` | LONG (64-bit integer) | Unique ID for each Usage Record sent. Duplicate received event IDs indicate possible retransmissions. | | `cost` | DECIMAL(14,10) | Does not reflect the real world cost, 1:1 translation of usage. | | `currency` | JSON Object | Currency object with information about the cost currency. See [Cost](#cost-object) for more information. | | `start_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage start in the ISO 8601 format. | | `end_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage end in the ISO 8601 format. | | `volume` | JSON Object | Object with the exact volume used as part of the Usage Record. See [Volume](#volume-object) for more information. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Event Organization](#organization-object) for more information. | | `operator` | JSON Object | Operator information, see [Operator](#operator-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM](#sim-object) for more information. | | `tariff` | JSON Object | Tariff details, see [Tariff](#tariff-object) for more information. | | `traffic_type` | JSON Object | Type of traffic of the Usage Record, see [Traffic Type](#traffic-type-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint](#endpoint-object) for more information. | *** ## Cost Object The cost object is set as a 1:1 relation to the used volume. It does not reflect the real world cost. | Property | Data Type | Description | | :------- | :---------------- | :--------------------------------------------------- | | `id` | INTEGER | Unique identifier of the currency of indicated cost. | | `symbol` | UTF-8 Char STRING | Symbol of the currency as UTF-8 Char. | | `code` | ISO 4217 STRING | Currency Code in ISO format. | *** ## Organisation Object {#organization-object} Information about the organization of the SIM that generated the volume usage record. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of the organisation. | | `name` | STRING | 1NCE Customer ID. | *** ## SIM Object Details about the SIM that is responsible for the volume usage. | Property | Data Type | Description | | :---------------- | :-------------- | :---------------------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | | `production_date` | TIMESTAMP (UTC) | Timestamp when the SIM was produced in the ISO 8601 format. | *** ## Operator Object Operator the SIM was attached to when the usage was generated. | Property | Data Type | Description | | :-------- | :---------- | :------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of visited operator. | | `mnc` | STRING | Mobile Network Code of the roaming operator. | | `name` | STRING | Name of the roaming mobile operator. | | `country` | JSON Object | Country information object, see [Country](#country-object) for more information. | *** ## Country Object Country of the device with the 1NCE SIM where the usage was generated. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------ | | `id` | INTEGER | Unique identifier of visited country. | | `mcc` | STRING | Mobile Country Code of the operator. | | `name` | STRING | Name of visited country. | *** ## Tariff Object Specific tariff assigned to the 1NCE SIM. | Property | Data Type | Description | | :--------- | :---------- | :----------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of applied tariff. | | `name` | STRING | Name of the applied tariff. | | `ratezone` | JSON Object | Ratezone information object, see [Ratezone ](#ratezone-object) for more information. | *** ## Ratezone Object The ratezone in which the SIM generated the indicated usage. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of applied Ratezone. | | `name` | STRING | Name of the Ratezone. | *** ## Traffic Type Object Identifies what kind of traffic was used and is shown in the Usage Record. This could either be Data or SMS.
Property Data Type Description

id

INTEGER

Unique identifier of traffic type. 5 = Data 6 = SMS

name

STRING

Name of traffic type either "Data" or "SMS".
*** ## Endpoint Object Details about the endpoint/device with the 1NCE SIM that generated the usage. | Property | Data Type | Description | | :----------- | :-------- | :------------------------------------------- | | `id` | INTEGER | Unique identifier of traffic type. | | `tags` | STRING | User-defined tags set for this endpoint. | | `ip_address` | STRING | The IP address assigned to this endpoint. | | `imei` | STRING | The IMEI of the endpoint hardware. | | `name` | STRING | The user-defined name set for this endpoint. | | `balance` | STRING | | *** ## Volume Object Exact volume, either data in MegaBytes or number of SMS used by the SIM.
Property Data Type Description

total

DECIMAL(14,6)

Total traffic consumed, sum of tx and rx.

tx

DECIMAL(14,6)

Dependent on Traffic Type: Upstream traffic (MB) send by the endpoint. or Number of sent MO-SMS

rx

DECIMAL(14,6)

Dependent on Traffic Type: Downstream traffic (MB) received by the endpoint. or Number of sent MT-SMS
--- # SMS Forwarder Service Source: https://help.1nce.com/docs/platform-services/platform-services-sms-forwarder/
![Schematic diagram of the structure of the SMS Forwarder Service.](/img/platform-services/platform-services-sms-forwarder/001.png)
As a counter part for Mobile Terminated (MT) SMS messages which are received by a mobile connected device, the 1NCE SMS Forwarding Services provides an interface for receiving Mobile Originated (MO) SMS messages. While MO-SMS can be viewed in the 1NCE Portal, it is cumbersome to use for large batches of SIM devices and can not be used for automation. For more details about this service, refer to the subchapters in the menu on the left side. The Forwarding Services provides HTTP Post/Patch messages for all SIM devices of an organization using the SMS Service. With the SMS Forwarding Server, MO-SMS messages and Delivery Reports (DLR) for MT-SMS are forwarded to a customer-specified HTTP endpoint as JSON objects. This chapter covers the basic working principle of the SMS Forwarding Service, the message events and a short setup guide to get the forwarder working in a practical use case. --- # Error States Source: https://help.1nce.com/docs/platform-services/platform-services-sms-forwarder/sms-forwarder-error-states/ If the configured HTTP endpoint is wrong or the defined server endpoint does not respond with HTTP 200, an error event is generated and pushed via the Data Streamer and the 1NCE Portal. The image below shows two typical error states for the SMS Forwarder. 1. A MO-SMS could not be delivered to the configured HTTP Post endpoint. Please check the customer-side server implementation. 2. A MT-SMS Delivery Report could not be delivered to the configured HTTP Patch endpoint. Verify the customer-side implementation. Take a look at Testing SMS Forwarder for debugging the custom endpoint. In both cases, the retry mechanism will try to redeliver the forwarded messages for 24 hours. After this timepoint, the messages will be discarded and set to the *Failed* state. If there are any uncertainties or issues during the troubleshooting, feel free to contact the 1NCE Support.
![SMS_Console_Error.png](/img/platform-services/platform-services-sms-forwarder/sms-forwarder-error-states/138194a-SMS_Console_Error.png)
--- # SMS Events Source: https://help.1nce.com/docs/platform-services/platform-services-sms-forwarder/sms-forwarder-events/ The 1NCE SMS Forwarding Service provides different types HTTP messages for Mobile Originated (MO) and Mobile Terminated (MT) SMS. In the following sections, the message events for MO-SMS and MT-SMS are outlined and an example JSON message is shown as reference. # MO-SMS Normal Mobile Originated SMS messages issued from devices with a 1NCE SIM are forwarded to the specified HTTP endpoint as JSON objects in a fixed format. The JSON message body contains parameter field which specify the payload and additional configurations. Listed below is an overview of these values from the HTTP Post Body of a MO-SMS message. | Property | Data Type | Description | | :-------------------- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the SMS message. | | `payload` | STRING | SMS message payload. The format (Alphabet Text, Binary Data, etc.) depends on the set Data Coding Scheme (DCS) value. | | `submit_date` | STRING | Timestamp of when the SMS message was send by the mobile device. | | `destination_address` | STRING | Phone number specified by sending party as destination. This parameter is ignored by the 1NCE SMS Service. | | `source_address` | STRING | MSISDN of the SIM card that send the SMS message. The MSISDN is the phone number of the SIM. | | `dcs` | INTEGER | The Data Coding Scheme (DCS) is a value which transports information about how the recipient device shall handle the the transferred data payload. | | `endpoint` | JSON OBJECT | Details about the originating SIM. The Name lists the ICCID of the SIM. | | `organisiation` | JSON OBJECT | Contains the internal organisation ID, not to be confused with the 1NCE organisation ID. | | `multi_part_info` | JSON OBJECT | Information about multi-part SMS messages. The parameters list the current part number and the total amount of messages in the concatenated message. | A JSON object with the listed parameters will be send with a HTTP Post request towards the specified customer endpoint for the SMS Forwarding Service. Below an example of such a JSON message is shown. ```json SMS Receive JSON Format { "id": 6202, "payload": "message text", "submit_date": "2018-08-17 16:31:51", "dest_address": "12345", "source_address": "", "dcs": 0, "endpoint": { "id": 8765412, "name": "" }, "organisation": { "id": 4567 }, "multi_part_info": { "partno": 1, "total": 1, "identifier": 6202 }, "pid": 0 } ``` # MT-SMS For Mobile Terminated SMS where the message is send towards a SIM device, the SMS Forwarding Service is not forwarding the actual SMS message itself to the application server. Instead, only the Delivery Report (DLR) of the MT-SMS is sent via the Forwarding Service.\ The DLR indicates the successful delivery of the MT-SMS using a 1NCE SIM card. When a MT-SMS is sent to a device via the 1NCE Portal or the 1NCE API, the SMS Forwarding Service provides a Delivery Report (DLR) in a JSON format. Below, the parameters of the HTTP Patch Body from the DLR message are explained. | Property | Data Type | Description | | :------------- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the DLR message. | | `final_date` | STRING | Timestamp when the MT-SMS was finalized by the receiving SIM device. | | `submit_date` | STRING | Timestamp when the MT-SMS was originally issued. | | `organisation` | JSON OBJECT | Contains the internal organisation ID, not to be confused with the 1NCE organisation ID. | | `endpoint` | JSON OBJECT | Details about the originating SIM. The Name lists the ICCID of the SIM. | | `status` | JSON OBJECT | Indication of the delivery status of the MT-SMS. The DLR response could be DELIVERED or FAILED when the MT-SMS was not successfully transmitted. | In contrast to the MO-SMS, the JSON object for the DLR of the MT-SMS will be send with a HTTP Patch request towards the specified customer endpoint. Below an example of such a JSON message is shown. ```json Delivery Report JSON Format { "id": 2819195, "final_date": "2020-06-09 15:06:38", "submit_date": "2020-06-09 15:06:34", "organisation": { "id": 4567 }, "endpoint": { "name": "", "id": 8765432 }, "status": { "id": 4, "status": "DELIVERED" } } ``` --- # Features & Limitations Source: https://help.1nce.com/docs/platform-services/platform-services-sms-forwarder/sms-forwarder-features-limitations/ # Features ## SMS Automation The usage of the SMS Forwarder is optional. By default MT- and MO-SMS messages of the last seven days are shown in the SMS Console in the 1NCE Portal. The Forwarder Services allows for an easy integration into automated processes without the need to constantly query the 1NCE API. The service pushes new incoming SMS messages and delivery reports towards the customer specified endpoint. 1NCE recommends using the Forwarding Service for automation of receiving regular, larger batches of SMS messages in a publish-subscribe manner. ## MO-SMS Reception With the 1NCE SMS Forwarding Service, Mobile Originated (MO) SMS messages can be forwarded to a customer specified HTTP endpoint. The incoming messages from the SIMs of the organization are delivered as JSON objects with additional SMS parameters. These additional parameters indicate multi-part SMS, the used encoding and references to the originating SIM of the message. The figure below shows an example sequence (successful and failed) of the MO-SMS delivery using the SMS Forwarding Service.
![Schematic sequence diagram of a MO-SMS reception.](/img/platform-services/platform-services-sms-forwarder/sms-forwarder-features-limitations/001.png)
## MT-SMS Delivery Report Outgoing, Mobile Terminated (MT) SMS which are send from the 1NCE Portal or API, generate Delivery Reports (DLR) when processed by the recipient. The SMS Forwarding Services also provide these DLR messages in the form of HTTP Patch requests to the customer endpoint. The DLR messages include in the JSON Body the delivery status of the send MT-SMS, timestamps of the delivery and SMS submission and references to the SIM that the SMS was send toward. The figure below shows an example sequence (successful and failed) of a Delivery Report for a MT-SMS being delivered through the SMS Forwarding Service. The initial MT-SMS was issued via the 1NCE Portal or the 1NCE API.
![Schematic sequence diagram of a MT-SMS DLR reception.](/img/platform-services/platform-services-sms-forwarder/sms-forwarder-features-limitations/002.png)
# HTTP Request Interface With the SMS Forwarding Server, MO-SMS messages and Delivery Reports (DLR) for MT-SMS are forwarded to a customer-specified HTTP REST endpoint as JSON objects.\ The customer needs to provide a REST Interface, which accepts HTTP Post/Patch requests issued from the 1NCE SMS Forwarding Service. The server needs to have a valid domain with HTTPS capabilities. To an incoming HTTP Post/Patch request, the server should reply with an HTTP 200 status code.\ For more details about the setup and testing visit the SMS Forwarder Example Guide. *** # Limitations ## MO-SMS and DLR Reception Only The SMS Forwarding Service is only intended to receive MO-SMS and DLR for MT-SMS. Thus, it is not possible to use this service to push or publish any kind of SMS message towards the SIM devices. It is intended as a publish-subscribe listening service. To issue new MT-SMS towards a SIM device, the 1NCE API or 1NCE Portal SMS Console have to be used instead. ## Organization Restriction It is only possible to setup one SMS Forwarder per organization. This forwarder will then receive the MO-SMS and DLR for all SIMs of the particular organization instance. This will not include the SIMs and messages of any sub- or parent-organization SIM devices. ## Retry Mechanism & Message Consumption When a configured SMS Forwarding endpoint is not reachable, redelivery for 24 hours in case of no HTTP 200 status response is attempted. Afterwards the messages will be dropped. If events can not be delivered to a configured forwarder, an error will written in the 1NCE Data Streamer and shown in the 1NCE Portal.\ Messages acknowledged with HTTP 200 are consumed by the customer-side HTTP endpoint and are therefore not redelivered. Still, the event messages will still be visible in the 1NCE Portal and accessible through the 1NCE API for seven days. --- # Setup Guides Source: https://help.1nce.com/docs/platform-services/platform-services-sms-forwarder/sms-forwarder-setup-guides/ --- # SIM Knowledge Source: https://help.1nce.com/docs/sim-cards/sim-cards-knowledge/ Many associate a tiny piece of plastic, which has an embedded chip, with the term SIM card. A chip that is inserted into a mobile phone or other modem to allow a specific device to connect to some sort of mobile network for internet and messaging connectivity. As usual, there is more than meets the eye when it comes to the details of a SIM. From a basic point of view, a Subscriber Identity Module (SIM) is an Integrated Circuit (IC) with a Card Operating System (COS) which stores security features used to authenticate the subscriber devices in a mobile network.
![Developer_Hub_SIM_Cards.png](/img/sim-cards/sim-cards-knowledge/0b742fa-sim.png)
*Overview of the different 1NCE IoT SIM form factors.* This data includes a unique serial number (ICCID), International Mobile Subscriber Identity (IMSI), security authentication, and ciphering information to authenticate the SIM as a valid subscriber to a mobile network. Further, temporary local network information, access service list, Personal Identification Number (PIN), and a Personal Unblocking Key (PUK) is stored on a SIM. The following sections will cover the basics of some SIM parameters that show up as part of the 1NCE Services. It is important to understand their role in the 1NCE ecosystem, as these parameters are useful for general information, device identification, troubleshooting and security. *** # Personal Identification Number (PIN) All 1NCE SIM cards are preassigned a 6-digit Personal Identification Number (PIN), which is disabled by default. The SIM cards are ready to use and no PIN validation needs to take place because of it. For devices controlled by AT-Commands, it is a good idea to use the general AT-Command 'AT+CPIN?' to test if the 1NCE SIM card is ready for operation. This tests if the SIM card is ready for operation when booting up a modem with a 1NCE SIM inserted. The AT-Command should return 'READY', indicating that the SIM is recognized and ready for operation. *** # Integrated Circuit Card Identifier (ICCID) SIM cards are mainly identified by their Integrated Circuit Card Identifier (ICCID), an identifier of the actual SIM card chip itself. ICCIDs are also used to identify embedded SIM (eSIM) profiles. This ID can be up to 23 digits long, including a check digit calculated using the Luhn algorithm. The ICCID conforms to the ITU E.118 numbering standard. Note that an extra digit is sometimes returned using AT-Commands, but this is not an official part of the ICCID. The ICCID is used throughout the 1NCE ecosystem (1NCE Portal, API, Data Streamer, etc.) as a common parameter to identify each SIM provided by 1NCE. The following table shows the structural components of the ICCID for 1NCE SIMs.
Component Length & Example
ICCID Integrated Circuit Card Identifier 16 - 23 Digits: 89 88 280 666xxxxxxxx x 89 88 228 0666xxxxxxx x
IIN Issuer Identification Number 4 - 9 Digits: 89 88 228 89 88 280
  MII Major Industry Identifier 2 Digits: 89 - Telecommunications
  CC Country Code 1 - 3 Digits: 88 - No Geolocation (IoT Application)
  II Issuer Identifier 1 - 4 Digits: 228 - 1NCE 280 - 1NCE
SIM - ID ID Number 11 - 13 Digits: 666xxxxxxxx 0666xxxxxxx
C Checksum 1 Digit: x - Luhn Algorithm
*** # International Mobile Subscriber Identity (IMSI) The International Mobile Subscriber Identity (IMSI) identifies SIM cards uniquely by their individual operator in a cellular network. The IMSI is stored as a 64-bit field and is communicated to the connected cellular network. In the core of a mobile operator network, the IMSI is used as main identification for obtaining further customer and device specific data. The IMSI is used across all global mobile networks. The IMSI conforms to the ITU E.212 numbering standard. Not to confuse the IMSI with the ICCID, the ICCID is the id of the physical SIM, while the IMSI is part of a profile placed on the SIM. In the 1NCE ecosystem, the IMSI is often found alongside the ICCID. The following table shows the structural components of the IMSI for 1NCE SIMs.
Component Length & Example
IMSI International Mobile Subscriber Identity 13 - 15 Digits: 901 40 51000xxxxx
  MCC Mobile Country Code 3 Digits: 901 - Worldwide Shared Mobile Country Code 454 - Hong Kong
  MSISN Mobile Subscriber ISDN Number 8 - 9 Digits: 51000xxxxx - Mobile Subscriber ISDN Number
## MCC and MNC The Mobile Country Code (MCC) and Mobile Network Code (MNC) identify a country of domicile and a operator of that network in this country. Both together result in the Public Land Mobile Network (PLMN) code of the mobile subscriber. Since the 1NCE SIM cards are not bound to a real country or network these values are defined as: MCC-901 and MNC-40. The MCC-901 has a special meaning, i.e. this is a shared Mobile Country Code which is used worldwide instead of identifying a certain country. Hence, 1NCE as IoT-MNO has reserved the PLMN 901-40 for their purposes and uses it for the standard 1NCE product. *** # Mobile Station International Subscriber Directory Number (MSISDN) The Mobile Station International Subscriber Directory Number (MSISDN) is used together with the IMSI to uniquely identify a SIM subscription in the global mobile network. A normal non-IoT carrier uses the MSISDN for routing voice calls to a subscribed SIM. While the IMSI for a specific profile on a SIM does not change over time, the MSISDN can change. The MSISDN format is defined in the ITU-T E.164. In the 1NCE ecosystem, the MSISDN can be found in the detail properties of a SIM using the API or Data Streamer Service. Compared to the ICCID, IMSI or IMEI, the MSISDN plays less of an important role for the 1NCE IoT use cases. *** # International Mobile Equipment Identity (IMEI) Certain parameters reported in the 1NCE ecosystem are not sourced from the 1NCE SIM but rather relate to the specific device used in conjunction with the SIM card. Such a parameter is the International Mobile Equipment Identity (IMEI). It is a unique number for the identification of a mobile SIM device modem. Each standardized modem that uses any type of SIM to connect to a mobile network operator has a unique IMEI. The IMEI, 15 digits: 14 + check digit, or IMEISV, 16 digits: 14 + two (software version), consists of information on the origin, model, and serial number of the device. The structure of the IMEI/SV is specified in 3GPP TS 23.003. In the 1NCE ecosystem, the IMEI/SV is used to identify individual devices and manufacturers. In the 1NCE Data Streamer and API, the IMEI/SV for some roaming operators might have an additional 'f' at the end of the IMEI.
Component Length & Example
IMEI International Mobile Equipment Identity 15 - 16 Digits: 86 995103 xxxxxx x - IMEI 86 995103 xxxxxx xx - IMEISV
  TAC Type Allocation Code 8 Digits: 86 995103 - Example of SIM 7000G
  SNR Serial Number 6 Digits: xxxxxx - Unique per Device
  CD/SVN Check Digit or Software Version 1 - 2 Digits: x - Check Digit xx - Software Version Number
## IMEI Lock Each device in a mobile network has an IMEI number which identifies the hardware uniquely when connecting to a network. 1NCE offers the functionality to lock a given device to the SIM card using the IMEI. If the IMEI lock is enabled during an active PDP data session, the current session will be dropped and the device forced to reconnect instantly. This ensures that the currently in use device is locked to the SIM and there is no possibility to change the SIM to another device after enabling the IMEI lock feature. Once the IMEI Lock option is enabled, the network will link the IMEI to the specific SIM card. Subsequent connection attempts with this SIM card using another device with different IMEI are blocked. This feature can be disabled and enabled by the customer for each SIM card individually either via the 1NCE Portal or 1NCE API. For the IMEI Lock functionality the IMEISV is used. The IMEISV is derived by the IMEI and includes the additional software version parameter. --- # 1NCE IoT SIMs Source: https://help.1nce.com/docs/sim-cards/sim-cards-overview/ 1NCE offers a range of IoT SIMs to meet different customer needs, shown in the following image.
![1NCE Standard SIMs compared to 1NCE eUICC SIMs](/img/sim-cards/sim-cards-overview/32d7638-Freedom_to_switch.webp)
*IoT SIMs provided by 1NCE* # IoT SIM Card Business This is a 3-in-1 plastic SIM card used for our 1NCE IoT Lifetime Flat. This SIM is best suited for off-the-shelve, ready-to-use IoT devices. It easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features makes the 1NCE IoT SIM Card Business ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. It does not support the Freedom to Switch feature (eUICC).
![](/img/sim-cards/sim-cards-overview/5785ebf-cliu9g5y5003i0rqmejpnayyt-sim-card.max.png)
# IoT SIM Card Industrial This SIM has all the same capabilities of the IoT SIM Card Business but comes with **Freedom to Switch** (eUICC feature) which enables to change the SIM profile in the future.
![](/img/sim-cards/sim-cards-overview/7882db0-SIM_industrial.png)
# IoT SIM Chip Industrial The IoT SIM Chip is identical to the IoT SIM Card with the **Freedom to Switch** eUICC feature, but comes in the MFF2 form factor. The IoT SIM Chip Industrial form factor is optimized for typical IoT device environments factors like heavy vibration and higher temperature ranges but also increased security. 1NCE recommends the integration of IoT SIMs Chip Industrial in custom-developed IoT devices and use cases where strong environmental robustness is needed.
![](/img/sim-cards/sim-cards-overview/c1c6c6d-chip.png)
--- # IoT SIM Card Business Source: https://help.1nce.com/docs/sim-cards/sim-cards-overview/sim-cards-iot-business/ Although the first, traditional plastic-backed SIM cards were introduced to the mobile network market over 30 years ago, the adapted form factor and technical specifications still apply today as a major key for mobile network communication. As part of the 1NCE connectivity services, the plastic 3in1 IoT SIM Card Business offers the fundamental entrance to the world of mobile IoT communication. This section will cover the basics about the physical IoT SIM Card Business form factor, technical specifications as well as recommendations for IoT hardware application cases.
![Overview of the 1NCE 3in1 IoT SIM Card Business, which includes the 2FF, 3FF and 4FF form factors.](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/613cd18-cliu9g5y5003i0rqmejpnayyt-sim-card.max.png)
*** # SIM Form Factor Over the years, with the hardware miniaturization and especially IoT use cases for mobile networks, the physical SIM Card format was adapted multiple times to make the overall footprint smaller. As the SIM chip design and layout was retained to provide backwards combability, the surrounding plastic format was changed. As a result, four common SIM Card form factors (1-4 FF) were established. Original full-size SIM Cards (1FF) had the typical credit card form factor. As this standard is used only rarely today, it has been phased out of production. The remainder 2FF, 3FF and 4FF are still commonly used and sold as 3in1 breakout, plastic-backed SIM Cards. The four SIM Card form factors are specified in ETSI TS 102 221. The exact dimension specifications of the form factors are listed in the table below. | | 2FF - Mini SIM | 3FF - Micro SIM | 4FF - Nano SIM | | :------------ | :------------- | :-------------- | :----------------------- | | **Height** | 25mm | 15mm | 12.3mm ± 0.1 mm | | **Width** | 15mm | 12mm | 8.8mm | | **Thickness** | 0.76mm | 0.76mm | 0.67mm +0.03 mm/-0.07 mm | 1NCE IoT SIM Card Business are 3in1 plastic-backed SIMs which incorporate the standardized 2FF Mini, 3FF Micro and 4FF Nano form factors. The 1NCE SIMs are shipped in a half-size carrier to make handling and shipping of the breakout SIMs easier. Depending on the customer needs the IoT SIM Card Business can be carefully broken down into the needed form factor and also reassembled back up to 2FF Mini with the supplied adapters.
![1NCE_4FF_SIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/20aeb83-1NCE_4FF_SIM_Dimensions.png)
*1NCE IoT SIM Card Business 4FF reference dimensions and pin assignment as of ETSI TS 102 221.* As 4FF is the smallest form factor that minimizes the plastic-backed SIM Card to the bare IC, we will use it as reference for the pinout. The pinout is the same for all IoT SIM Card Businesses as the SIM IC is identical. Shown above is the pinout reference and dimensions of the 4FF SIM according to ETSI TS 102 221. While the 1NCE IoT SIM Card Business 4FF and IoT SIM Chip Industrial form factor are different, the pinout of the actual ICs are the same. The pinout table references the pinout of the dimensional reference figure for the 4FF SIM Card.
Contact Pin Spec. Description 1NCE IoT SIM Card Business Pinout

C1

VCC Supply Voltage

VCC

C2

RST Reset Pin

RST

C3

CLK Clock Signal

CLK

C4 and C8

Optional USB interface according to ETSI TS 102 600

N/A

C5

GND Ground Connection

GND

C6

VPP Programming Voltage

N/A

C7

I/O Input Output Data

I/O
*** # Shipping & Assembly Packaging 1NCE 3in1 IoT SIM Card Business Cards are packaged in a half-size breakout card to save on plastic wastage. This makes handling and shipping of the different SIM form factors easier. Each of these breakout cards, shown below, contains one 3in1 SIM. For easier identification, a barcode and numerical representation of the EAN code and the ICCID are printed on the back of the cards. When ordering low quantities of IoT SIM Card Business, the cards will be packaged and shipped in small plastic wrapped packages. For larger orders will be fulfilled by shipping boxes of 100 or 500 SIMs respectively. These boxes are packaged in sequence, lowest to highest ICCID with a label sticker indicating the first and last ICCID of the box.
![1NCE_FlexSIM.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/a2dce8795d72eda003b894480f74b2ca4184cc2a229c63e32e0fc2a1dbf7baab-SIMCBusiness.png)
*1NCE 3in1 IoT SIM Card Business inside the half-size breakout card used for easier shipping and packaging.* *** # SIM ICCID Identification Each SIM Card can be uniquely identified by the ICCID. This SIM identification is used throughout the 1NCE ecosystem to mark each unique SIM. The ICCID can be read by the hardware modem using an AT-Command or manufacturer specific request. For easier physical identification, each 1NCE IoT SIM Card Business has the ICCID of the particular SIM printed on the 4FF physical chip card. *** # IoT SIM Card Business Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIM Card Business comply with these technical standard specifications. Besides the key standard compliances, SIM Cards are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Card Business specifications that are relevant for the deployment of the 1NCE IoT SIM Card Business. Furthermore, references to the key standard compliances for the SIM interfaces are referenced.
Parameter 1NCE IoT SIM Card Business (3in1)
Form Factors (FF) 2FF - Mini, 3FF - Micro, 4FF - Nano
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -25°C to +85°C
Operating Voltages Class A, B and C (1.8V –5.0V ±10%)
Data Retention Period min. 10 years
Read/Write Cycles min. 500 000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # IoT SIM Card Business Application Cases As the plastic-backed IoT SIM Card Business remains the most commonly used form factor in the mobile communication field, this SIM serves as the ideal general-purpose solution for most off-the-shelf, ready-to-use IoT devices. The 3in1 form factor of the 1NCE IoT SIM Card Business is compatible with a wide range of devices which accept this standardized form factor. This form factor of SIM is easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features make the 1NCE IoT SIM Card Business ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. For any open questions about the detailed 1NCE IoT SIM Card Business product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # IoT SIM Card Industrial Source: https://help.1nce.com/docs/sim-cards/sim-cards-overview/sim-cards-iot-industrial/ The form factor of the IoT SIM Card Industrial is identical to the IoT SIM Card Business with the plastic 3in1 format. The main differences are within the SIM chip, software and environmental ruggedness of the SIM card. This section will cover the basics about the physical IoT SIM Cards Industrial form factor, technical specifications as well as recommendations for IoT hardware application cases.
![Overview of the 1NCE 3in1 IoT SIM Cards Industrial, which includes the 2FF, 3FF and 4FF form factors. ](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/e7a6860-SIM_industrial.png)
*** # IoT SIM Cards Industrial Form Factor Over the years, with the hardware miniaturization and especially IoT use cases for mobile networks, the physical SIM Card format was adapted multiple times to make the overall footprint smaller. As the IoT SIM Chip Industrial design and layout was retained to provide backwards combability, the surrounding plastic format was changed. As a result, four common IoT SIM Cards Industrial form factors (1-4 FF) were established. Original full-size IoT SIM Cards Industrial (1FF) had the typical credit card form factor. As this standard is used only rarely today, it has been phased out of production. The remainder 2FF, 3FF and 4FF are still commonly used and sold as 3in1 breakout, plastic-backed SIM Cards. The four IoT SIM Cards Industrial form factors are specified in ETSI TS 102 221. The exact dimension specifications of the form factors are listed in the table below. | | 2FF - Mini SIM | 3FF - Micro SIM | 4FF - Nano SIM | | :------------ | :------------- | :-------------- | :----------------------- | | **Height** | 25mm | 15mm | 12.3mm ± 0.1 mm | | **Width** | 15mm | 12mm | 8.8mm | | **Thickness** | 0.76mm | 0.76mm | 0.67mm +0.03 mm/-0.07 mm | 1NCE IoT SIM Cards Industrial are 3in1 plastic-backed SIMs which incorporate the standardized 2FF Mini, 3FF Micro and 4FF Nano form factors. The 1NCE IoT SIM Cards Industrial are shipped in a half-size carrier to make handling and shipping of the breakout SIMs easier. Depending on the customer needs the IoT SIM Cards Industrial can be carefully broken down into the needed form factor and also reassembled back up to 2FF Mini with the supplied adapters.
![1NCE_4FF_SIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/20aeb83-1NCE_4FF_SIM_Dimensions.png)
*1NCE IoT SIM Cards Industrial 4FF reference dimensions and pin assignment as of ETSI TS 102 221.* As 4FF is the smallest form factor that minimizes the plastic-backed SIM Card to the bare IC, we will use it as reference for the pinout. The pinout is the same for all IoT SIM Cards Industrial as the SIM IC is identical. Shown above is the pinout reference and dimensions of the 4FF SIM according to ETSI TS 102 221. While the 1NCE IoT SIM Cards 4FF and eSIM MFF2 form factor are different, the pinout of the actual ICs are the same. The pinout table references the pinout of the dimensional reference figure for the 4FF IoT SIM Cards Industrial.
Contact Pin Spec. Description 1NCE IoT SIM Cards Industrial Pinout

C1

VCC Supply Voltage

VCC

C2

RST Reset Pin

RST

C3

CLK Clock Signal

CLK

C4 and C8

Optional USB interface according to ETSI TS 102 600

N/A

C5

GND Ground Connection

GND

C6

VPP Programming Voltage

N/A

C7

I/O Input Output Data

I/O
*** # Shipping & Assembly Packaging 1NCE 3in1 IoT SIM Cards Industrial are packaged in a half-size breakout card to save on plastic wastage. This makes handling and shipping of the different SIM form factors easier. Each of these breakout cards, shown below, contains one 3in1 SIM. For easier identification, on the back of the cards a barcode and numerical representation of the EAN code and the ICCID is printed. When ordering low quantities of IoT SIM Cards Industrial, the cards will be packaged and shipped in small plastic-wrapped packages. For larger orders will be fulfilled by shipping boxes of 100 or 500 SIMs respectively. These boxes are packaged in sequence, lowest to highest ICCID with a label sticker indicating the first and last ICCID of the box.
![1NCE_FlexSIM.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/dd1d47b257ed4b77c15c798869af49d8c7b6912c34ff71810aa6754e0bbcaf19-SIMCIndustrial.png)
*1NCE 3in1 IoT SIM Cards inside the half-size breakout card used for easier shipping and packaging.* *** # IoT SIM Cards Industrial eID Identification An eID is a 32-digit global unique identifier number, containing information that uniquely identifies the physical SIM. Using the eUICC feature, the eID is the most important number to identify the SIM as the ICCID may change with the active profile. The eID is unique to the IoT SIM, and will remain always the same. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM Card Industrial has the eID of the particular SIM printed on the 4FF physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # IoT SIM Cards Industrial Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIM Cards Industrial complies with these technical standard specifications. Besides the key standard compliances, SIM Cards are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Cards Industrial specifications that are relevant for the deployment of the 1NCE IoT SIM Cards Industrial. Furthermore, references to the key standard compliances for the SIM interfaces are listed.
Parameter 1NCE IoT SIM Card Industrial (3in1)
Form Factors (FF) 2FF - Mini, 3FF - Micro, 4FF - Nano
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -40°C to +105°C
Operating Voltages Class A, B and C (1.62V – 5.5V)
Data Retention Period min. 10 years
Number of profiles max. 10
Read/Write Cycles min. 2.000.000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # IoT SIM Cards Industrial Application Cases As the plastic-backed IoT SIM Cards Industrial is currently still the most commonly used form factor in the mobile communication field, it is best suited as a general-purpose SIM for most off-the-shelve, ready-to-use IoT devices. The 3in1 form factor of the 1NCE IoT SIM Cards Industrial is compatible with a wide range of devices that accept this standardized form factor. This form factor of SIM is easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features make the 1NCE IoT SIM Cards Industrial ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. Also, 1NCE IoT SIM Cards Industrial are ideal for more demanding environments due to their enhanched physical attributes, for example, operating temperature. For any open questions about the detailed 1NCE IoT SIM Cards Industrial product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # IoT SIM Chip Industrial Source: https://help.1nce.com/docs/sim-cards/sim-cards-overview/sim-chips-iot-industrial/ The traditional plastic-backed SIM originated from the user equipment (UE) usage for telecommunication where customers needed to exchange SIMs easily as the devices were not bound to a particular SIM. Starting in 2016, the embedded SIM (eSIM) or embedded Universal Integrated Circuit Card (eUICC) gained interest from developers due to its smaller footprint and deeper integration possibilities. Especially in custom embedded Machine-to-Machine (M2M) and IoT hardware application cases, the IoT SIM Chip Industrial offers unique advantages compared to the traditional IoT SIM Card Business. In purpose-built IoT devices, there is no need for regular manual SIM Card swaps. Key factors like ruggedness, security and space constraints have high priority. For these special needs, the 1NCE IoT SIMs Chip Industrial provides the ideal solution. This section covers the 1NCE IoT SIM Chip Industrial product with its standardized form factor, technology specifications and outline recommended application cases.
![1NCE IoT SIM Chip Industrial MFF2 Integrated Circuit.](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/974e330-chip.png)
*** # IoT SIM Chip Industrial Form Factor As the IoT SIM Chip Industrial evolved from the traditional IoT SIM Card Business, it shares the same technological functionality but just in a smaller physical packaged form factor. The IoT SIM Chip Industrial format is commonly designated as MFF2. The 1NCE IoT SIM Chip Industrial conforms to this MFF2 footprint in a Quad-Flat No-Leads 8 (QFN8) Integrated Circuit (IC) package. The MFF2 package is specified in ETSI 102 671. The QFN8 IoT SIM Chip Industrial package is not mounted inside a socketed adapter like the IoT SIM Card Business, it is designed to be directly soldered to the Printed Circuit Board (PCB) of a device. QFN8 is an often used footprint in electronic devices. Thus, it can be easily integrated into automated assembly production lines of IoT-enabled devices. The specifications of the form factor are shown in the figure below.
![1NCE_eSIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/8f83e1d-1NCE_eSIM_Dimensions.png)
Embedded-SIMs share the same basic pinout as IoT SIMs Card Business but in a different form factor shown in the figure above. The following table references the pin assignments and lists their respective functional pinout. | Contact Pin | Spec. Description | 1NCE IoT SIM Chip Industrial Pinout | | --- | --- | --- | | C1 | **VCC** Supply Voltage | VCC | | C2 | **RST** Reset Pin | RST | | C3 | **CLK** Clock Signal | CLK | | C4 and C8 | **Optional** USB interface according to ETSI TS 102 600 | N/A | | C5 | **GND** Ground Connection | GND | | C6 | **VPP** Programming Voltage | N/A | | C7 | **I/O** Input Output Data | I/O | *** # Shipping & Assembly Packaging When ordering 1NCE IoT SIMs Chip Industrial, the QFN8 ICs are packaged in a standardized tape reel of 100, 500, 1000, 2500, and 3000 IoT SIMs Chip Industrial. These tape reels can be directly used in an automated production assembly line. 1NCE IoT SIMs Chip Industrial are packaged in 12mm wide tape, which is 1.2mm thick and covered with a plastic film to keep the IoT SIM Chip Industrial ICs in place until production. The packing process and materials meet the requirements defined in JEDEC J-STD-033 with ESD precautions and proper handling procedures. The tape is provided on 7-inch (178mm) and 13-inch (330mm) reels. For lots of 100 or 500 IoT SIMs Chip Industrial, 7-inch reels are used and for 1000, 2500 or 3000 IoT SIMs Chip Industrial 13-inch reels are used. **Package outline** ![](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/948f33a84761c2c4213387a79b00b93ada17bd9f27b427c05946effbe0481ca9-image.png) **Package Footprint** ![](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/7b3b41cd125600e0c8d6df30071c4aef89fcb9c1fa54cc4c86b4004f10c08a3e-image.png) **Tape & Reel packing** ![Infineon Integration Guide SLx16 SLx17](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/9fb616e62a74da6e4531c348a40b45daff2e61201909b0af1c8fc4f0b1db682a-image.png) Each reel is vacuum packaged separately with a humidity indicator card, desiccant and a barcode label in a reel cardboard box. The barcode label shows the first and last IoT SIM Chip Industrial ICCID of the specific reel. IoT SIMs Chip Industrial are produced in sequence in ascending order where the smallest ICCID is produced first and is at the end of the tape in the middle of the reel. The user direction of unreeling is according to EIA-481 standard.
![1NCE_eSIM_Reel.png](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/63be9d7-1NCE_eSIM_Reel.png)
*** # IoT SIM Chip Industrial eID Identification An eID is a 32-digit global unique identifier number, containing information that identifies the SIM supplier for the physical SIM. Using eUICC feature, the eID is the most important number to identify the SIM. The ICCID may change with the change of the active profile, but eID is unique to the IoT SIM, and it is always the same. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM Card Industrial has the eID of the particular SIM printed on the 4FF physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # IoT SIM Chip Industrial Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIMs Chip Industrial comply with these technical standard specifications. Besides the key standard compliances, SIM Chips are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Chip Industrial specifications that are relevant for the deployment of the 1NCE IoT SIM Chip Industrial. Furthermore, references to the key standard compliances for the SIM interfaces are referenced.
Parameter 1NCE IoT SIM Chip Industrial
Form Factor (FF) MFF2, QFN8 (IC Package)
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -40°C to +105°C
Operating Voltages Class A, B and C (1.62V – 5.5V)
Data Retention Period min. 10 years
Number of profiles max. 10
Read/Write Cycles min. 2.000.000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # Application Cases IoT SIM Chip Industrial Embedded-SIMs reduce the footprint of the SIM integration and also provide a more rugged and robust connection. In general, the IoT SIM Chip Industrial form factor is more optimized for typical IoT device environments where factors like heavy vibration, higher temperature ranges but also increased security plays a key role. 1NCE recommends the integration of IoT SIMs Chip Industrial in custom developed IoT devices and use cases where extraordinary environmental robustness is needed.\ As the IoT SIMs Chip Industrial is surface mounted to the PCB of a device, it provides higher security against end-user tampering as the SIM Card cannot be easily removed. For prototyping and designing custom IoT devices, special QFN8 adapters are available to adapt an IoT SIM Chip Industrial to the IoT SIM Card Industrial footprint. For any open questions about the detailed 1NCE IoT SIM Chip Industrial product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # eUICC Knowledge Source: https://help.1nce.com/docs/sim-cards/sim-euicc-knowledge/ An eUICC (Embedded Universal Integrated Circuit Card) is a re-programmable SIM card that can be remotely provisioned with different operator connection profiles. This allows users to switch between different carriers without physically changing the SIM card. Unlike a traditional SIM card, which is tied to a specific carrier plan, an eUICC can be reprogrammed over the air (OTA) with new profiles. It simplifies logistics for device manufacturers and network operators, who no longer need to physically swap SIM cards when activating or switching devices between carrier plans. The following sections will cover the basics of 1NCE eUICC. *** # Remote SIM Provisioning (RSP) Remote SIM Provisioning (RSP) in IoT is the process of remotely managing SIM profiles saved on eUICC-capable SIM cards. This includes installation, switching, and deactivation of SIM profiles over-the-air. Before RSP, a change of an operator profile could only be done by physically changing the whole SIM card. With Remote SIM Provisioning, it has become possible to overcome the issues by allowing to add, switch or change a SIM profile remotely over-the-air (OTA). There is no physical difference between eUICC SIM cards and normal non-eUICC SIM cards. The eUICC SIMs are available as solderable MFF2 or put into the SIM slot when used in removable form factors (2FF, 3FF, 4FF). *** # SIM ICCID vs. eID A physical non-eUICC SIM is typically identified using the ICCID, which is printed on the SIM card or chip. When using eUICC, the ICCID can change dependent on the used profiles, thus the ICCID is no longer a static unique identifier. For eUICC SIMs, the eID, a 32-digit global unique identifier number, is used. It is unique and references the physical hardware SIM chip. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM has the eID of the particular SIM printed on the physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # 1NCE RSP Models 1NCE offers three kinds of models, Freedom To Switch, Overtake and Active Model. The differences between these models are explained below. For any open questions about the eUICC models or more extensive help for the specific application case, feel free to contact us (1NCE Contact). ## Freedom To Switch (Insurance) The insurance model is used when the customer requires a new physical eUICC SIM for their device. The 1NCE IoT SIM has the 1NCE profile stored as default. It works out of the box like the IoT SIM Card Business product, but It is possible to change the SIM profile in the future. These are the eUICC capable SIMs : **IoT SIM Card Industrial** and **IoT SIM Chip Industrial**. ## Overtake or Bring your own eUICC (BYOeUICC) If the customer already has an eUICC-capable SIM card from another provider and is using their own RSP platform, it is possible to migrate this eUICC SIM from the customer RSP to 1NCE RSP systems and add the 1NCE profile to the existing eUICC compatible SIM. 1NCE takes over not only the customer connectivity needs but also their eUICC SIMs into the 1NCE RSP platform.
![](/img/sim-cards/sim-euicc-knowledge/001.png)
## Active model 1NCE is looking forward to enabling a RSP ecosystem capable of integrating with other RSP platforms (where SIM profiles are stored). These integrations will allow the customer to actively host and switch between 1NCE and other connectivity profiles using the remote SIM provisioning capabilities. These integrations are standardized by the GSMA specifications. Once the integrations are in place, customers will be able to download profiles and switch between multiple profiles depending on their use case. The active model can be used in the followings scenarios: 1. The customer has an eUICC SIM from another provider and wants to use 1NCE profile for their device.
![](/img/sim-cards/sim-euicc-knowledge/002.png)
2. The customer has an eUICC SIM from 1NCE and wants to use another profile from another provider for their device.
![](/img/sim-cards/sim-euicc-knowledge/003.png)
# Device Requirements for eUICC-capable IoT SIMs The GSMA standards require that the device supports some features to enable the eUICC functionality. The minimum requirement is a device that fulfills the needs to enable the use of eUICC functions. Please note these features are mandatory for the eUICC to execute RSP operations only, for example, downloading profile, enabling a profile, deleting a profile, etc. In case your device does not support this, it will still work normally, which means fulfilling all your connectivity needs, but no profile swapping can happen. You may find more information about eUICC compatibility, providers, and modules [here](https://1nce.com/en-eu/euicc-sim-card-for-iot-esim/euicc-compatible-iot-hardware). --- # 1NCE Technical Support Source: https://help.1nce.com/docs/troubleshooting/troubleshooting-technical-support/ --- # Welcome Source: https://help.1nce.com/docs/v2/ This is the place to find the detailed technical documentation developers need to start digging into the 1NCE connectivity services. This guide focuses on general knowledge and technical application information for the sim services, connectivity services, platform services, network services, and API reference. If there are any issues or questions regarding the 1NCE services, feel free to contact our technical support (1NCE Contact). We are thankful for suggestions and feedback from our customers as we continue to improve and develop our services. Find the most viewed and recommended documentation chapters in the excerpts below for getting started with 1NCE services. To explore more of the Developer Hub, browse the menu on the left side. For quickly finding specific details, the search function helps to get the needed information. Click on the box header titles to be redirected to the individual chapters. - [Access Point Name (APN)](/docs/v2/connectivity-services/connectivity-services-data-services/data-services-apn/) — Connecting IoT devices using the 1NCE mobile services requires setting the APN. This chapter shows the basics about the Access Point Name used for the 1NCE services. - [API Explorer](/api/v2/) — Check the API Explorer to get to know the Management API and learn more about the usage and the general capacities. - [1NCE Portal Guide](/docs/v2/1nce-portal/portal-dashboard/) — The 1NCE Portal offers an easy-to-use web interface for managing all 1NCE SIMs and related services. The documentation guides show configuration possibilities and features of the 1NCE Portal. - [Data Services](/docs/v2/connectivity-services/connectivity-services-data-services/) — Data Services are essential for connecting devices to linked up cloud services. These guides provide an introduction into the data connectivity with 1NCE SIMs. - [SMS Services](/docs/v2/connectivity-services/connectivity-services-sms-services/) — Many IoT solutions still use SMS for basic configuration and messaging. With the 1NCE products SMS messaging is included. Learn how to use these services. - [Data Streamer Service](/docs/v2/platform-services/platform-services-data-streamer/) — All SIM devices generate network event and usage records as part of their normal operation. These events are useful for monitoring and debugging device behavior and usage statistics. Learn more about the 1NCE Data Streamer Service. - [VPN Service](/docs/v2/network-services/network-services-vpn-service/) — The VPN Service offers the passivity to bidirectionally connect to your 1NCE SIM card devices via a private network connection without using the public Internet Breakout. --- # Admin Logs Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-admin-logs/ As 1NCE OS is intended to ease the entry into IoT applications, the 1NCE Admin Logs provides an aggregator of events from devices and errors. From the Admin Logs, the events and errors can be viewed via the Web Interface or queried using the Management API for further processing. --- # API Examples Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-admin-logs/admin-logs-api/ The Admin Logs can be accessed via an API to allow customers to get their data in an automated way without going through the portal. The Admin Logs API description is available in the [API Explorer](/api/). *** # Examples ## Get Messages ### Device messages (7 days) Getting all messages for a specific device for 7 days for a device with `ICCID` that is `123456789012345678`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678" ``` The response looks like this: ```json { "items": [ { "id": "2LXBToi1yNaEWTiYYhyGS1AAerg", "customerId": "2000523120", "timestamp": "2023-02-10T09:21:15.634Z", "type": "DEVICE", "message": "Translator[UserPayloadError]", "description": "Asset path:longitude, Error: can't extract [0:8] from 1 bytes", "traceId": "1-63e60c8b-2c5f8668ca294dba54a16820", "category": "error", "imsi": "901408801893721", "ip":"10.209.106.1", "iccid":"123456789012345678", "payloadReference": "2000673166/2LXcToi1yNaEWTiYYhyGS1QBAerg" }, { "id": "2LEc7VjBK3AUtPa00WHQnOfd2cC", "customerId": "2000523120", "timestamp": "2023-02-03T12:50:56.800Z", "type": "LIFECYCLE", "message": "Lifecycle[DeviceFirstTimeRegistered]", "description": "New Device successfully registered for the first time - 8988228066601892721", "traceId": "1-63dd8630-364793628bf27f2b8c3cda07", "category": "info", "ip":"10.209.106.1", "iccid":"123456789012345678", }, ], "page":1, "pageAmount":2 } ``` In the response, one item from the specific device (ICCID “123456789012345678“) is shown. It is an error message coming from the translator service. ### Messages Time Range Getting messages in a specified time range for the same device but between `2022-02-21T13:20:00.000` and `2022-02-21T13:22:00.000`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?startDateTime=2022-02-21T13:20:00.000&endDateTime=2022-02-21T13:22:00.000" ``` Both of the query parameters are optional, but one should be given. If only `startDateTime` is provided, the query will consider the end date-time to be the current time. If only `endDateTime` is provided, the start date-time will be the time seven days ago. ### Working with Pagination By default, up to ten messages are returned from the API. The customer is able to specify the page size with the query parameter pageSize. The value of this parameter should be between 1 and 25. Example call to get a message of an example device in the page of three: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678&pageSize=3" ``` We can also go directly to a certain page by defining the parameter page. We would directly go to page number two with this request: ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs?iccid=123456789012345678&pageSize=3&page=2" ``` ### Calling endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs" ``` With this request you get the last ten messages from all devices within the last seven days. ## Get Message Stats ### Calling Message Stats endpoint To get the message statistics, you need to specify a timezone (mandatory) and you can filter on category if necessary. ```shell curl -X GET "https://api.1nce.com/management-api/v1/administrationLogs/stats?timezone=Europe%2FAmsterdam&category=info" ``` With this request you get the statistics for the timezone CET and we set a filter for the category `info`. We would get the following response: ```json { "totalUniqueDevices": 2, "administrationLogs": [ { "amount": 2, "day": "2022-03-07T00:00:00.000+0000" }, { "amount": 2, "day": "2022-03-08T00:00:00.000+0000" } ] } ``` --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-admin-logs/admin-logs-features-limitations/ # Features The Admin Logs provide the possibility to show info messages from lifecycle events and errors from all customer devices. Setting custom filters allows to search for certain messages: * Specific device context using ICCID. * Category: `Info` and `Error`. * Period: 1 day and 7 days. *** # Limitations Admin Logs limitations: * Admin Logs older than 7 days are removed automatically. * Admin Log payload value is saved in binary format. Lifecycle event limitation: * "DEVICE\_FIRST\_TIME\_REGISTERED" event is triggered only once per device, and there are no other configurations available for this. --- # Info category Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-admin-logs/admin-logs-info-category/ Open the Admin Logs in [1NCE OS](https://portal.1nce.com/portal/customer/connectivitysuite) to see the latest logs from the devices. Use the filter to get Info Category logs. ![](/img/1nce-os/1nce-os-admin-logs/admin-logs-info-category/admin-logs-info.png) ### Lifecycle There is currently one Lifecycle event available. ### DEVICE\_FIRST\_TIME\_REGISTERED * There is only one "DEVICE\_FIRST\_TIME\_REGISTERED" event possible for the device. * The event is triggered on the first interaction of the device with 1NCE OS by interacting with any of endpoints ([UDP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-udp/), [COAP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/), [LwM2M](/docs/v2/1nce-os/1nce-os-lwm2m/) registration), [Device Observability Memfault Plugin](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/) or using the [FOTA management Mender Plugin](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/) with a particular device. * Using "DEVICE\_FIRST\_TIME\_REGISTERED" event, customers can identify which devices have been activated and brought online at least once. --- # Web Interface Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-admin-logs/admin-logs-web-interface/ Open the Admin Logs in [1NCE OS](https://portal.1nce.com/portal/customer/connectivitysuite) to see the latest logs from the devices. At the top, the filter can be used for searching on ICCID, Category or the Time Period. The last 5 Admin Log Events and Errors are shown on the dashboard. ![Filter at the admin logs](/img/1nce-os/1nce-os-admin-logs/admin-logs-web-interface/filter-admin-logs.png) --- # Cloud Integrator Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/
![Cloud Integrator as part of the IoT Integrator](/img/1nce-os/1nce-os-cloud-integrator/IoT-Integrator.png)
The Cloud Integrator allows to create, manage and use 1NCE webhooks and direct AWS integrations. This provides the possibility for a customer to forward data from 1NCE services to customer-defined HTTPS endpoints or an AWS account with real-time information. Forwarded data depends on the selected event type. *** ### Event Types ### Telemetry Data Whenever a message (UDP, CoAP or LwM2M) from a device is sent to the 1NCE OS endpoint(s) the message is forwarded to the customer's Cloud Integrations. * LwM2M messages are forwarded to customer's Cloud Integrations. * Traversed UDP and CoAP messages will be forwarded to customer's Cloud Integrations. The forwarded message content depends on the energy saver status for the specific protocol. If the [Energy Saver](/docs/v2/1nce-os/1nce-os-energy-saver/) is not enabled, then message will be forwarded directly, but when enabled, then a processed message will be forwarded. ### Lifecycle Events This option will forward all the [Lifecycle](/docs/v2/1nce-os/1nce-os-admin-logs/admin-logs-info-category/#lifecycle) events from the Info category Admin Logs to the customer's Cloud Integrations. ### Error Events This option will forward all the Error category Admin Logs to the customer's Cloud Integrations. It also will include [Cloud Integration failure event](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/) ### Geofence Events Whenever a geofencing event "EXIT" or "ENTER" has been triggered by device location change the message is forwarded to the customer's Cloud Integrations. ### Location Events Whenever a device GPS location update has been sent using Energy Saver template or CellTower location event has been triggered, the location update event is forwarded to the customer's Cloud Integrations. ### Test Message Test Message can be triggered by [Test AWS Integration](/api/1nce-os/test-aws-integration/) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration/) endpoints. Test Message will be sent also during integration restart process. Integration restart is being initiated from customer after integration has been set to "INTEGRATION_FAILED". :::info A comprehensive set of examples for each event type can be found [here](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/#examples). ::: --- # AWS Configuration Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/ ## Prerequisites ### Security Token Service (STS) Endpoint In your AWS account the Security Token Service (STS) Endpoint should be enabled for eu-central-1 region.
![STS enabled for eu-central-1 region](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/STS-Endpoint.jpg)
### iot:Data-ATS Endpoint In your AWS account the iot:Data-ATS Endpoint should be enabled for region where you are rolling out AWS Integration.
![iot:Data-ATS Endpoint enabled for the customer’s chosen region](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/IoT-Endpoint.jpg)
### IAM role permissions To successfully roll out the CloudFormation (CFN) stack, the customer must ensure that all the permissions listed in [cfn stack description](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/#cfn-stack-description) are granted. ## Configuration via Frontend For setting up the AWS integration, use the Cloud Integration Wizard in the 1NCE OS portal.\ Click 'New Integration' and select AWS integration as integration type. Use a descriptive name and select the [event types](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/) that you would like to receive.
![Configuration of an AWS Integration in the 1NCE portal](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-aws-creation.png)
Be aware that integration with status ROLLOUT\_STARTED will be created in the Cloud Integrator and you will be taken to AWS to complete the configuration over there.\ This generates a JWT that is only valid for an hour. Once the JWT becomes invalid the rollout has to be restarted. After the configuration click proceed and you will be prompted to go to the AWS console. Continue and now AWS should be open on the 'Quick Create Stack' page. Here you will see things such as the name that was previously given, integration token, etc. If this information is correct, acknowledge AWS requirements and press 'create stack'.
![Creation of AWS stack](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/create-stack-1nceOS.png)
It will take some time for the stack to be created. Nested stacks are shown by the filter option 'view nested' on the top. Once it is done, it should look like this in AWS and 1nceOS portal respectively:
![AWS stack created](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/stack-created-1nceOS.png)
![Integration rolled out](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/rollout-done.png)
### Validate Integration *A device being able to send data is a prerequisite for this step. For more information refer to the cloud integrator[documentation](/docs/v2/1nce-os/1nce-os-cloud-integrator/).* Once your stack has been rolled out, you can test your integration using one of your devices or by using [Test AWS Integration](/api/1nce-os/test-aws-integration/) endpoint. In AWS go to the IoT Core service. Navigate to the MQTT test client and subscribe to # as shown below:
![MQTT Test Client](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/MQTT-test-1nceOS.png)
Doing this will subscribe to all topics so if the stack was successfully rolled out, you should see data show up as shown below:
![MQTT Test Client result](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/MQTT-response-1nceOS.png)
If the integration was successfully created, rolled out and actived, *Integration Active* will appear.
![Integration Active](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-active.png)
### Edit AWS integration It is possible to edit the 1nceOS integration options through the front-end by clicking the edit-button as shown below:
![1nceOS change integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/change-configuration.png)
### Restart AWS integration There is a possibility that your integration fails. When this happens, it will be visible in the 1nceOS portal as shown below:
![1nceOS restart integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/integration-restart.png)
By clicking the restart button, there will be an attempt to verify the integration. During that time an event of type TEST\_MESSAGE will be sent out. For more information refer to [event-type documentation](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/) ### Delete AWS Integration There are two ways to delete the integration: #### Front-end You can delete your AWS Integration in the front-end of 1NCE OS or using API. In this case, you need to delete your AWS stack manually.
![1nceOS delete integration](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/delete-integration.png)
#### AWS When the deletion is initiated from your AWS stack, there are no further actions needed. The callback function will automatically trigger the deletion of the AWS Integration in 1NCE OS.
![AWS delete stack](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/stack-deletion.png)
### CFN stack description The following section describes resources that will be deployed with the stack. Stack contains 3 nested stacks. ### AWS Integration Resource stack #### IAM cross account role Stack creates Cross Account IAM role with following permissions for 1NCE OS AWS account 672401624271: * 'iot:DescribeEndpoint' - Retrieve the AWS IoT endpoint. * 'iot:Publish' - Publish MQTT messages to AWS IoT Core.
![AWS Integration stack resources](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/aws-integration-stack.png)
### Callback stacks Two stacks are rolled out for callback operations: * Callback 'create' stack: Provisions resources required to complete the integration with 1NCE OS. * Callback 'delete' stack: Provisions resources that notify 1NCE OS when the stack is deleted from the customer's AWS account. Both the 'create' and 'delete' stacks provision identical resources.
![Callback ](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/delete-callback-stack2.png)
#### Download code lambda function A Lambda function that downloads the actual callback Lambda function. #### Callback lambda function The 'create' callback stack Lambda function notifies the 1NCE OS that the integration rollout has been successfully completed.\ The 'delete' callback stack Lambda function notifies the 1NCE OS when the CloudFormation stack is deleted from the customer's AWS account. Notifications are sent via API calls. #### S3 bucket S3 buckets where the actual code for the 'create' and 'delete' callback Lambda functions are placed. #### Stack execution IAM Role For each stack execution IAM role with the following permissions is created: Logs: * 'logs:CreateLogGroup' - Allows creation of CloudWatch Log Groups. * 'logs:CreateLogStream' - Allows creation of log streams within the created log groups. * 'logs:PutLogEvents' - Allows publishing log events to the created log streams. Customers S3 bucket: * 's3:DeleteObject' - Allows deletion of objects from the specified S3 bucket. * 's3:GetObject' - Allows reading objects from the specified S3 bucket. * 's3:ListBucket' - Allows listing objects in the specified S3 bucket. * 's3:PutObject' - Allows uploading (writing) objects to the specified S3 bucket. * 's3:GetBucketPolicy' - Allows retrieval of the bucket policy for the specified S3 bucket. * 's3:PutObjectTagging' - Allows adding or updating tags on an S3 object. 1NCE OS S3 bucket: * 's3:GetObject' - Allows reading objects from 1NCE OS S3 bucket. * 's3:GetObjectTagging' - Allows retrieving tags associated with an 1NCE OS S3 object. * 's3:ListBucket' - Allows listing objects in the 1NCE OS S3 bucket. ### Lambda runtime versions used in the different 1NCE OS customer stack versions ##### V1.0.0 * Download code lambda function: python3.9 * Callback lambda function: nodejs14.x ##### V1.1.0 * Download code lambda function: python3.9 * Callback lambda function: nodejs18.x ##### V1.2.0 (latest) * Download code lambda function: python3.13 * Callback lambda function: nodejs22.x --- # Cloud Integration failure event Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/ ## Cloud Integrations failure causes Cloud Integrator service automatically sets customer's AWS or Webhook integrations into the `Failed` state after 5 failed attempts to forward customer message to the AWS or Webhook integration. If integration is set to `Failed` state - an [Admin Log](/docs/v2/1nce-os/1nce-os-admin-logs/) will be generated. Here are some possible failure reasons: * Webhook Integration: - if customer's Webhook destination endpoint is not reachable. - does not return response in 20 seconds. - HTTPS endpoint for some reason starts returning non 2xx response. * AWS IoT Core Integration: - AWS IoT Core outage in the destination AWS Region. - misconfiguration in the customer's AWS Account. ## Cloud Integrations failure monitoring To prevent cases when customer Cloud Integration suddenly gets into the `Failed` state and customer does not notices it for some time, there is possibility to subscribe to `Error` type Admin Logs. It can be done using separate dedicated Webhook or AWS Cloud Integration, where customer can filter out Error events with the type `CloudIntegrator[IntegrationDisabled]`. Following `Error` Cloud Integrator event will be generated with the integration id and name in the `description` field: ```json { "received": "1762351834991", "id": "1-690b5ada-31707a98fb4bf676304a55e2", "type": "ERROR", "error": { "payloadExists": false, "description": "Integration with ID C-_wsByVWIW8PCq4OI82C and name \"Broken_Webhook\" was disabled due to consecutive failed requests. Please review affected integration details in Cloud Integrator.", "id": "353vzrcOpHi4YYbyl0bVYlwURAU", "type": "INTEGRATION", "message": "CloudIntegrator[IntegrationDisabled]" }, "version": "1.0.0" } ``` Also on the 1NCEOS frontend page you will see following Admin Log:
![](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/integration-admin-log.png)
*Integration Failed Admin Log* Following steps should be executed: * Create a dedicated HTTPS endpoint or a separate AWS Account (or region) with AWS IoT Core enabled for monitoring. * Create either Webhook or AWS Integration with only `Error` events type selected. * Implement filtering logic by `type` field on that new Cloud Integration to get notifications in case if type is equal to `CloudIntegrator[IntegrationDisabled]`. ## Restart process In case if it happens customer have to execute following steps: * Check Webhook's HTTPS endpoint or AWS IoT Core configuration in your's AWS Account for any possible reasons why those can return errors. * Trigger restart using one of the possible approaches: - Using following [Restart AWS Integration](/api/1nce-os/restart-aws-integration/) or [Restart Webhook Integration](/api/1nce-os/restart-webhook-integration/) API endpoints. - Restart also can be triggered in the 1NCEOS Cloud Integrator frontend page, see [Restart AWS Integration](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-aws-configuration/#restart-aws-integration) --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-features-limitations/ # Features * Receiving LwM2M messages to clients endpoint. * Receiving traversed UDP and CoAP messages to clients endpoint. * In total, there will be five attempts to send the message via Webhook or to AWS with an exponential retry policy (150s, 180s, 420s, 1020s). * Own headers can be specified for webhooks. * Device metadata can be injected in the Webhook's URL and headers. See more details [here](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/#metadata-injection-in-webhook-definitions). * Integrations can be tested by sending TEST_MESSAGE [event type](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/). This can be done by using [Test AWS Integration](/api/1nce-os/test-aws-integration/) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration/) endpoints. * The "First Successful Message Delivery" timestamp reflects the time of the first successful message sent to the Integration by device after this Integration was created. * In case of Cloud Integration Failure, special Error Admin Log entry will be created, which can be used for monitoring [Cloud Integration failure events](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/). *** # Limitations * Only HTTPS POST webhook endpoints are supported. Endpoints should respond with 2xx HTTP status code. * Customer endpoint should respond within 20s. * Same customer endpoint URL **CANNOT** be set to multiple webhooks simultaneously. * Integrations will be set to state `integration failed` after 5 unsuccessful message forwarding attempts. If needed, they can be restarted manually. * "First Successful Message Delivery" value will be updated only on first successfull message sent by device after Integration is created/rolled out. * Integration state will not be changed if a test message will be sent to the integration. * Customer webhook endpoints with self-signed certificate are not supported. * Customer webhook endpoint domains with special characters are not supported. In case special characters should be used, please refer to `punycode`. * Data is sent in JSON-Format: * For all LwM2M Messages. * For all UDP and CoAP messages that are being processed with Energy Saver template. * If `Parse JSON payload` is enabled and that message is a valid parsable JSON. * Data is sent in Base64 format: * If `Parse JSON payload` is disabled. * If `Parse JSON payload` is enabled but that message is NOT a valid parsable JSON. * Only device metadata can be injected into a webhook's definition, such as :iccid:, :imsi: and :ip: --- # Output Format Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/ ## AWS Integration MQTT Topics For AWS Integrations the messages will be forwarded to a dedicated AWS IoT Core MQTT topic for each event type. | Event Type | AWS IoT Core MQTT Topic | | --- | --- | | ERROR | `error` | | GEOFENCE | `geofence` | | LOCATION | `location` | | LIFECYCLE | `lifecycle` | | TELEMETRY_DATA | LWM2M & UDP protocol: `{{iccid}}/messages` CoAP protocol with provided [query parameter _t_](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/): `{{iccid}}/{\{query\_parameter\_t}}` CoAP protocol without provided [query parameter _t_](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/): `{{iccid}}` | | TEST_MESSAGE | `integration-status` | *** ## Examples ### TELEMETRY_DATA ```json { "payload": { "type": "JSON", "value": { "latitude": 7.490929188596135e+247, "longitude": 2.586343401687847e+161 } }, "received": "1670598749915", "id": "1-6393505d-67fa8489fb9c791fcddd43f0", "source": "UDP", "type": "TELEMETRY_DATA", "version": "1.0.0", "device": { "iccid": "8988280666000002864", "ip": "100.91.200.24", "imsi": "901405100002864" } } ``` ### LIFECYCLE ```json { "lifecycle": { "type": "DEVICE_FIRST_TIME_REGISTERED", "message": "New Device successfully registered for the first time - 8988280666000002864" }, "received": "1670830184814", "id": "1-6396d868-d00f68b911b75bc761768e9b", "type": "LIFECYCLE", "version": "1.0.0", "device": { "iccid": "8988280666000002864", "ip": "100.91.200.24", "imsi": "901405100002864" } } ``` ### ERROR ```json { "id": "1-87654321-4fff5fb82c196babcd00008", "type": "ERROR", "received": "1649931594333", "device": { "iccid": "1234567890123456789", "imsi": "987654321098765", "ip": "127.0.0.1" }, "error": { "id": "3dsd627637267sahdgyasd", "type": "DEVICE", "message": "Translator[UserPayloadError]", "description": "Asset path:Temperature, Error: can't extract [200:201] from 2 bytes", "payloadExists": true }, "version": "1.0.0" } ``` ### GEOFENCE ```json { "id": "1-87654321-4fff5fb82c196babcd00007", "type": "GEOFENCE", "received": "1649931594333", "geofence": { "id": "Wg9ys5VqmSNN8M8YN2rv8", "name": "TEST_GEOFENCE_1", "coordinates": ["24.166234790073986","56.977086867785"], "source": "CellTower", "type": "EXIT" }, "device": { "ip": "100.91.200.20", "iccid": "1234567890123456789", "imsi": "987654321098765" }, "version": "1.0.0" } ``` ### LOCATION ```json { "id": "1-87654321-4fff5fb82c196babcd00007", "type": "LOCATION", "received": "1649931594333", "location": { "source": "CellTower", "coordinates": ["24.166234790073986","56.977086867785"], "metadata": { "verticalAccuracy": 45, "verticalConfidenceLevel": 0.68, "horizontalAccuracy": 303, "horizontalConfidenceLevel": 0.68 } }, "device": { "ip": "100.91.200.20", "iccid": "1234567890123456789", "imsi": "987654321098765" }, "version": "1.0.0" } ``` :::warning Note that `metadata` parameter with accuracy data is only available in **Plus** CellTower locator mode. ::: ### TEST_MESSAGE This event can be triggered by [Test AWS Integration](/api/1nce-os/test-aws-integration/) or [Test Webhook Integration](/api/1nce-os/test-webhook-integration/) endpoints. This event will be triggered also if an integration with status `INTEGRATION_FAILED` will be restarted. ```json { "id": "1-63d889d3-d987cbb90f8f10c76278d8dd", "type": "TEST_MESSAGE", "received": "1675135445411", "integration": { "id": "X8qB3FhJQyffUH0GqL3gC", "name": "integration-name" }, "version": "1.0.0" } ``` *** # Message Properties These are the properties of a message. It contains parameters that help to identify the message and the device that has sent the message. | Property | Data Type | Description | Present in event types. *Optional | | :---------- | :---------- | :--------------------------------------------------------------------------------------------------- | :---------------------------------------------------- | | type | ENUM | Source event type. Values: `LIFECYCLE`, `TELEMETRY_DATA`, `ERROR`, `GEOFENCE`, `TEST_MESSAGE` | All | | received | STRING | UNIX Timestamp. Received message date and time in milliseconds since midnight, January 1, 1970 UTC. | All | | source | ENUM | Values: `UDP`, `COAP`, `LWM2M` | TELEMETRY_DATA | | version | STRING | Version number of our Payload-Format. With new version, format can change. | All | | id | STRING | Unique ID for each message sent. | All | | device | JSON Object | Object describing device from which the message was received. | TELEMETRY_DATA, GEOFENCE, LIFECYCLE, *ERROR, LOCATION | | payload | JSON Object | Object describing message payload. | TELEMETRY_DATA | | lifecycle | JSON Object | Lifecycle object. | LIFECYCLE | | error | JSON Object | Object describing error. | ERROR | | geofence | JSON Object | Object describing geofence event. | GEOFENCE | | integration | JSON Object | Object describing integration. | TEST_MESSAGE | | location | JSON Object | Object describing location. | LOCATION | *** # Payload Properties These are the properties of a message payload object. It contains message payload properties. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------------------------------------------------------------------------------------------- | | type | ENUM | Values: `JSON`, `STRING` | | encoding | ENUM | Present only for UDP and COAP raw messages that hasn't been traversed through translation service. Values: `base64`. | | value | see type | Payload value. | | topic | STRING | Present only for COAP messages. | *** # Device Properties These are the properties of a message device object. It contains parameters that help to identify the device that has sent the message. | Property | Data Type | Description | | :------- | :-------- | :--------------------------------- | | iccid | STRING | Device iccid. | | imsi | STRING | Device imsi1. | | ip | STRING | Device ip address in 1nce network. | *** # Lifecycle properties These are the properties for lifecycle events and it is present only for lifecycle messages. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | type | ENUM | Values: `DEVICE_FIRST_TIME_REGISTERED` | | message | STRING | Description of lifecycle event | # Error properties These are the properties of a message error object. It is present only for error messages. | Property | Data Type | Description | | :------------ | :-------- | :----------------------------------------------------- | | id | STRING | Error id | | type | ENUM | Values: `DEVICE`, `GENERAL`, `INTEGRATION`, `LOCATION` | | message | STRING | Short error message | | description | STRING | Detailed error description | | payloadExists | BOOLEAN | Does Error contains payload | # Geofence properties These are the properties of a message geofence object. It is present only for geofence messages. | Property | Data Type | Description | | :---------- | :----------- | :--------------------------------------------------------------------------------------- | | id | STRING | Geofence id | | type | ENUM | Values: `EXIT`, `ENTER` | | name | STRING | Name of geofence | | coordinates | STRING ARRAY | Coordinate of location which triggered the geofence event [ longitude, latitude ] | | source | ENUM | Values: `GPS`, `CellTower` | # Integration properties These are the properties of a message integration object. | Property | Data Type | Description | | :------- | :-------- | :------------------ | | id | STRING | Integration id | | name | STRING | Name of integration | # Location properties These are the properties of a message location object. It is present only for location messages. | Property | Data Type | Description | | :---------- | :----------- | :--------------------------------------------------------------------------------------- | | source | ENUM | Values: `GPS`, `CellTower` | | coordinates | STRING ARRAY | Coordinate of location which triggered the location event [ longitude, latitude ] | | metadata | OBJECT | **Optional** JSON field with position metadata like vertical accuracy, country, etc | --- # Webhook Configuration Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/ To start using the Cloud Integrator with webhook integration, an HTTPS endpoint should be created. The endpoint could be either an IP address or a domain name. Depending on the customer's network security - it is possible\ that the webhook source IPs should be whitelisted. The following IPs will forward data to the webhook endpoint(s): * 52.29.71.11 * 18.157.211.95 # Configuration via Frontend ## Webhook Creation To create a webhook you should at least define an own integration name and an endpoint URL. Further fields that can be specified are: * [Event Types](/docs/v2/1nce-os/1nce-os-cloud-integrator/#event-types) to listen to. * Custom HTTP headers for webhooks. * Whether non-translated messages should be parsed to JSON, if possible.
![Configuration of a Webhook in the Frontend](/img/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/webhook-creation.png)
# Webhook Configuration via API ## Webhook Creation * Headers object in the request body should contain authorization and configuration headers that are expected by the customer's endpoint. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "webhook-name-1", "url": "https://www.your-endpoint.com/messages1", "headers": {"x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ"}, "eventTypes": [{ "type": "TELEMETRY_DATA" }] }' ``` ### Metadata Injection in Webhook Definitions Webhook definitions support metadata injection in the `url` and `headers` fields using placeholders.\ These placeholders will be automatically replaced with data from the device that triggered the event, such as telemetry\ data or location events. The following placeholders can be used in the `url` and `headers` fields: | Placeholder | Description | Default Value (if unavailable) | | ----------- | ------------------------ | ------------------------------ | | `:iccid:` | ICCID of the device | `none` | | `:imsi:` | IMSI1 of the device | `none` | | `:ip:` | IP address of the device | `none` | :::info If an event does not contain the required data, the corresponding placeholder will be replaced with `none` ::: :::warning If a webhook definition contains an unsupported placeholder, it will remain unchanged. ::: #### Examples Consider the following webhook configuration: ```json { "name": "webhook-name-1", "url": "https://www.your-endpoint.com/events?iccid=:iccid:&ip=:ip:&imsi=:imsi:", "headers": { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": ":imsi:", "x-device-iccid": ":iccid:", "x-device-ip": ":ip:" }, "eventTypes": [{ "type": "TELEMETRY_DATA" }] } ``` #### Scenario - Full Device Metadata Injection For an event coming from a device with the following attributes: * **ICCID**: `1234567890123456789` * **IMSI**: `987654321098765` * **IP**: `192.168.1.1` The webhook request will be transformed as follows: * **URL:**\ `https://www.your-endpoint.com/events?iccid=1234567890123456789&ip=192.168.1.1&imsi=987654321098765` * **Headers:** ```json { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": "987654321098765", "x-device-iccid": "1234567890123456789", "x-device-ip": "192.168.1.1" } ``` #### Scenario - Missing Metadata For an admin log event that is unrelated to a specific device, no metadata can be injected an the placeholders will be\ replaced with `none`. The webhook request will be transformed as follows: * **URL:**\ `https://www.your-endpoint.com/events?iccid=none&ip=none&imsi=none` * **Headers:** ```json { "x-api-key": "ABCDEFGHIJKLMNOPQRSTUVWXYZ", "x-device-imsi": "none", "x-device-iccid": "none", "x-device-ip": "none" } ``` #### Scenario - Unsupported Placeholders If a webhook definition contains an unsupported placeholder, it will remain unchanged. ```json { "name": "webhook-name-2", "url": "https://api.example.com/data?destination=:unknown:", "headers": { "x-tracking": ":tracking_id:" } } ``` Since `:unknown:` and `:tracking_id:` are not supported, the resulting webhook request will be: * **Final URL:** `https://api.example.com/data?destination=:unknown:` * **Headers:** ```json { "x-tracking": ":tracking_id:" } ``` ## Get all Integrations ```curl curl --location --request GET 'https://api.1nce.com/management-api/v1/integrate/clouds' ``` Response Example: ```json { "page":1, "pageAmount":1, "items": [ { "id":"AP3dIUs3c7_Oo2yJYaXWg", "name":"test_integration", "state":"INTEGRATION_FAILED", "type":"WEBHOOK", "createdTime":"2022-11-22T12:16:30.814Z", "updatedTime":"2022-11-23T08:07:19.354Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" }, { "type":"TELEMETRY_DATA", "version":"1.0.0" } ] }, { "id":"Jv2cS-pPcy0NdtQ64ycZJ", "lastSuccessfulMessageDelivery":"2022-12-07T12:29:51.927Z", "name":"beeceptor-webhook-int", "state":"INTEGRATION_ACTIVE", "type":"WEBHOOK", "createdTime":"2022-09-16T11:01:11.390Z", "updatedTime":"2022-12-09T11:23:48.609Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" }, { "type":"TELEMETRY_DATA", "version":"1.0.0" } ] }, { "id":"MzSca5vvHAfJ4MUUCfCGb", "name":"rollout-started-int", "state":"ROLLOUT_STARTED", "type":"AWS", "createdTime":"2022-10-17T13:30:15.309Z", "updatedTime":"2022-10-17T13:30:15.309Z", "eventTypes": [ { "type":"LIFECYCLE", "version":"1.0.0" } ] } ] } ``` ## Integration Edit To edit your webhook integration via API, you can use following curl request: ```curl curl --request PATCH \ --url https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId} \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data ' { "eventTypes": [ { "type": "LIFECYCLE" } ], "url": "www.example.com", "jsonPayloadEnabled": false } ' ``` ## Test Integration To send test message to your webhook integration via API, you can use following curl request: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/test' ``` :::info Any metadata injection placeholder will resolve to `none` ::: :::info This functionality does not update "First Successful Message Delivery" field value. ::: ## Integration Restart After 5 unsuccessful message attempts for a webhook it will be set to state `INTEGRATION_FAILED`. To restart the webhook: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/integrate/clouds/webhooks/{integrationId}/restart' ``` :::info Any metadata injection placeholder will resolve to `none` ::: :::info This functionality does not update "First Successful Message Delivery" field value. ::: --- # Device Authenticator Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-authenticator/ ![](/img/1nce-os/1nce-os-device-authenticator/device-authenticator.png) ## Device Authenticator The Device Authenticator offers a secure and automatic onboarding service for devices. The Device Authenticator is based on the Sim-as-an-Identity principle. Through unique identifiers, each SIM Card is securely authenticated and can be immediately used to send data to the [device integrator](/docs/v2/1nce-os/1nce-os-device-integrator/). ## Sim-as-an-Identity The `ICCID` of the customer SIM is used as a unique identifier for the device. --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-authenticator/device-authenticator-features-limitations/ ## Features The Device Authenticator solution is part of 1NCE OS and allows customers a seamless and fully automated device onboarding. ## Limitations The Device Authenticator works only with enabled Breakout regions, which currently include Europe (Frankfurt), US East (N. Virginia), and Asia-Pacific (Tokyo). For more details, see [Internet Breakout](/docs/v2/network-services/network-services-internet-breakout/). ## Security Security is the highest focus for the Device Authenticator. Each SIM Card is authenticated by the 1NCE core network using unique identifiers like IMSI, MSISDN and IMEI (if the IMEI Lock is activated by the customer). Additionally, the static, private IP addresses is used in the 1NCE core network to identify and check each data package processed by 1NCE OS to validate the authentication of the device. To keep the devices functional and authenticated it should remain with the same SIM. Further security is guaranteed through an encrypted communication between the device and 1NCE OS using DTLS for CoAP or LwM2M. --- # Device Controller Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-controller/ The Device Controller supports sending messages to the device via the 1NCE OS managed services. For that we offer three protocols in Device Integrator.
![Device Controller as part of the IoT Integrator](/img/1nce-os/1nce-os-device-controller/IoT-Integrator.png)
--- # API Examples Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-controller/device-controller-api/ The Device Controller can be accessed via an API to allow customers to send data to the devices in an automated way without going through the portal.\ The Device Controller API description is available in the [API Explorer](/api/). # Examples ## Create Action Request An action request can include different fields per protocol. Therefore, an example request body is given for every protocol. ### UDP Creating UDP action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/UDP" ``` The request body looks like this: ```json { "payload": "Data to send to the device", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" } ``` ### CoAP Creating CoAP action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/COAP" ``` The request body looks like this: ```json { "payload": "Data to send to the device", "payloadType": "STRING", "port": 3000, "path": "/example?param1=query_param_example", "requestType": "POST", "requestMode": "SEND_NOW" } ``` ### LwM2M Creating LwM2M action request for a device with deviceId `123456789012345678`: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/LWM2M" ``` The request body looks like this: ```json { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "requestMode": "SEND_WHEN_ACTIVE" } ``` ### Bulk request Creating LwM2M action request for multiple devices: ```shell curl -X POST "https://api.1nce.com/management-api/v1/integrate/devices/actions/LWM2M" ``` The request body looks like this: ```json { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "requestMode": "SEND_WHEN_ACTIVE", "deviceIds": ["123456789012345678", "123456789012345679", "123456789012345680"] } ``` ### Retry Mechanism When submitting an action request with `SEND_WHEN_ACTIVE` mode, the user can specify the parameter `sendAttempts` in\ the request body to restrict how many times the device controller can attempt to send the data to the device. \ If all attempts fail, then the action request will be permanently marked with the status `FAILED`. The `sendAttempts` parameter is optional and, if unspecified, defaults to 1. \ The maximum number of allowed retries is 5. :::warning Please note that this functionality is **NOT supported by the UDP protocol**. ::: ### Request Body Properties These are the properties of a request body. It specifies when and which message will be sent to the device. | Property | Data Type | Description | Available for protocol. \*Optional | | :-------------- | :-------- | :------------------------------------------------------------------------------------------- | :--------------------------------- | | payload | STRING | Data to send to the device. | UDP, \*CoAP | | payloadType | ENUM | Type of the payload. Values: `STRING`, `BASE64`. | UDP, \*CoAP | | port | INTEGER | Communication port number of a device. | UDP, CoAP | | requestMode | ENUM | Values: `SEND_NOW`, `SEND_WHEN_ACTIVE` (when a device sends a message). Default: `SEND_NOW`. | \*UDP, \*CoAP, \*LwM2M | | path | STRING | Absolute path to the resource. | CoAP | | requestType | ENUM | Method used to send message. Values: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`. | CoAP | | action | ENUM | LwM2M action name. Values: `read`, `write`, `execute`, `observe-start`, `observe-end`. | LwM2M | | resourceAddress | STRING | LwM2M OMA object resource address. | LwM2M | | data | STRING | Data to send to the device. | \*LwM2M | | sendAttempts | INTEGER | The maximum number of attempts to send data to the device. Default: 1 | \*CoAP, \*LWM2M | *** Note that for LwM2M there's no possibility to provide a data type for the `data` property. For LwM2M we support 8 data types: TIME, STRING, BOOLEAN, INTEGER, FLOAT, UNSIGNED\_INTEGER, OBJLINK and OPAQUE. The data type depends on the addressed resource. Users should provide the data in a stringified format (base64 encoded string for OPAQUE). In case an invalid data type for a resource is used, an Admin Log will be created. ### Response The API will accept the request with a `202 Accepted` response code and a response body containing two properties: id (string) and message (string). The id can be used to track the status of the request or cancel the request (see examples below). The message property contains a confirmation message about the request created. Example: ```json { "id": "trxHeBL0d234fsfds", "message": "Action read for resource /3/45/22 successfuly scheduled for device 123456789012345678." } ``` ## Get action request(s) Get action request(s) endpoints are available to track the status of the request and potentially see the response from a device using CoAP/LwM2M. The `requestData` property return protocol-specific request data provided when the request was created. For LwM2M the `responseData` can contain the following properties if available: `code` (response code), `payload` (data from the device), for Coap there is also additional field - `payloadType` (payload type). The `payloadType` is either `TEXT` when the response content format is printable, or `BASE64` if the content format is not printable or not present at all. In case an error occurs, the field `errorMessage` is present in the `responseData`. ### By specific requestId Getting request with id `trxHeBL0d234fsfds`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds" ``` The response could be `200 OK` with body: ```json { "id": "trxHeBL0d234fsfds", "status": "SUCCEEDED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "LWM2M", "created": "2024-08-22T11:14:28.157Z", "updated": "2024-08-22T11:14:28.157Z", "mode": "SEND_WHEN_ACTIVE", "resultData": { "code": "205", "payload": "Data from the device", "payloadType": "TEXT" }, "requestData": { "action": "write", "resourceAddress": "/3311/0/5850", "data": "Data to send to the device", "iccid": "123456789012345678", "imsi1": "456789012345678", "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1", "deviceId": "123456789012345678", "requestId": "trxHeBL0d234fsfds", "customerId": "1234567890", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1" }, "sendAttemptsLeft": 0, "sendAttempts": 3 } ``` For LwM2M `resultData` could be ```json { "resultData": { "code": "205", "payload": "Data from the device" } } ``` For CoAP `resultData` printable text: ```json { "resultData": { "code": "205", "payload": "Data from the device", "payloadType": "TEXT" } } ``` For CoAP `resultData` binary text: ```json { "resultData": { "code": "205", "payload": "RGF0YSBmcm9tIHRoZSBkZXZpY2U=", "payloadType": "BASE64" } } ``` ### By using the optional filter query parameters There are 2 endpoints available that support query parameters and are meant to query action requests by different statuses: [Active action requests](/api/1nce-os/get-active-device-action-requests/) are those which have statuses `IN_PROGRESS `and `SCHEDULED` [Archived action requests](/api/1nce-os/get-archived-device-action-requests/) are those which have statuses `CANCELLED`,`FAILED` and `SUCCEEDED` Getting multiple **archived** requests with optional filters (query parameters) specified. For example, to get all LwM2M action requests that succeeded for a device with id 123456789012345678:: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/archived?protocol=LWM2M&deviceId=123456789012345678&status=SUCCEEDED" ``` The response could be `200 OK` response code with body: ```json { "items": [ { "id": "2l0mG3WulN1SUvlIcHjvKXBeZk0", "status": "SUCCEEDED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "LWM2M", "created": "2024-08-22T11:14:28.157Z", "updated": "2024-08-22T11:14:28.157Z", "mode": "SEND_WHEN_ACTIVE", "resultData": { "code": "205", "payload": "Data from the device" }, "requestData": { "data": "Data to send to the device", "iccid": "123456789012345678", "imsi1": "456789012345678", "action": "write", "traceId": "1-66c71d94-f8f46a5cb7ae4ac4def607f1", "deviceId": "123456789012345678", "requestId": "2l0mG3WulN1SUvlIcHjvKXBeZk0", "customerId": "1234567890", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1", "resourceAddress": "/3311/0/5850" }, "sendAttemptsLeft": 0, "sendAttempts": 3 } ], "page": 1, "pageAmount": 1 } ``` Getting multiple **active** requests with optional filters (query parameters) specified. For example, to get all UDP action requests that are scheduled for a device with id 123456789012345678:: ```shell curl -X GET "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/active?protocol=UDP&deviceId=123456789012345678&requestMode=SEND_WHEN_ACTIVE" ``` The response could be `200 OK` response code with body: ```json { "items": [ { "id": "2l0kyyq0zGSuc1C78NKe5Pc3Auk", "status": "SCHEDULED", "deviceId": "123456789012345678", "ip": "127.0.0.1", "protocol": "UDP", "created": "2024-08-22T11:03:59.267Z", "updated": "2024-08-22T11:03:59.267Z", "mode": "SEND_WHEN_ACTIVE", "requestData": { "port": 4343, "iccid": "123456789012345678", "imsi1": "456789012345678", "payload": "Hello world", "traceId": "1-66c71b1f-64f6213bb0ea04d2f5784494", "deviceId": "123456789012345678", "requestId": "2l0kyyq0zGSuc1C78NKe5Pc3Auk", "customerId": "1234567890", "payloadType": "STRING", "requestMode": "SEND_WHEN_ACTIVE", "deviceIpAddress": "127.0.0.1" }, "sendAttemptsLeft": 1, "sendAttempts": 1 } ], "page": 1, "pageAmount": 1 } ``` ## Delete action request(s) The delete endpoint is used the cancel requests. This means `SCHEDULED` requests will be updated to the status `CANCELLED`. The messages will not be sent to the device. ### By specific requestId Delete request with id `trxHeBL0d234fsfds`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/actions/requests/trxHeBL0d234fsfds" ``` The response could be `200 OK` response code with body: ```json { "id": "trxHeBL0d234fsfds", "status": "CANCELLED" } ``` ### By deviceId Delete all requests for device with id `123456789012345678`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/integrate/devices/123456789012345678/actions/requests" ``` The response could be `200 OK` response code with body: ```json [{ "id": "trxHeBL0d234fsfds", "status": "CANCELLED" }] ``` --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-controller/device-controller-features-limitations/ # Features * Sending messages to IoT devices using UDP, CoAP and LwM2M. * Message for single device and [bulk devices](/docs/v2/1nce-os/1nce-os-device-controller/device-controller-api/#bulk-request) are supported. * Schedule message to be send when we receive a message from the device or on LwM2M registration and update events (requestMode `SEND_WHEN_ACTIVE`) * Cross-protocol trigger: sending a message from the device with any protocol to the 1NCE OS endpoint will trigger sending scheduled messages for all protocols to the device * Possibility to cancel a scheduled request * Possibility to cancel all scheduled requests for a device * See the response from the device for CoAP and LwM2M * Possibility to configure [retries](/docs/v2/1nce-os/1nce-os-device-controller/device-controller-api/#retry-mechanism) for scheduled CoAP or LwM2M messages. * Track the status of action requests. Available values: * `SCHEDULED`: the request was created with requestMode `SEND_WHEN_ACTIVE`. The request hasn't been sent to device and is still pending for a trigger to occur. * `IN_PROGRESS`: the request was created with requestMode `SEND_NOW`, or was scheduled and a trigger occurred * `SUCCEEDED`: device responded with 2.xx response code via CoAP or LwM2M. Or message was sent via UDP (there's no validation a message via UDP was received). * `FAILED`: device responded with 4.xx or 5.xx response code via CoAP or LwM2M. Or an unexpected error occurred. Check the `resultData` of the request for more details. Only for CoAP, if the actual response data fails to be saved (e.g. malformed payload), then the Action request finishes with a `FAILED` state. * `CANCELLED`: a scheduled request was cancelled via the DELETE endpoints of our API
![Action request lifecycle](/img/1nce-os/1nce-os-device-controller/device-controller-features-limitations/device-controller.png)
*** # Limitations :::warning For CoAP Actions the device should send ACK to Device Controller IP from which the message was received **instead of sending ACK to[CoAP Server](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/)** ::: * A maximum of 10 Messages can be scheduled per device * Maximum 100 devices are allowed to be selected for each request * Scheduled messages (requestMode `SEND_WHEN_ACTIVE`) are expired and sent to `FAILED` status if not triggered during 24 hours * Requests will be deleted 7 days after the creation date, independent of the status of the request. * A maximum UDP payload size of 508 bytes * A maximum CoAP payload size of 1024 bytes * CoAP DTLS is currently not supported * The maximum number of send attempts for SEND_WHEN_ACTIVE requests is 5. * For CoAP Actions only, the response body (if available) will be visible as either a plain string or a Base64 encoded value, depending on the Content-Format of the response. If no Content-Format is provided, then Base64 is the default one. * According to [RFC7252 section 4.8](https://www.rfc-editor.org/rfc/rfc7252.html#section-4.8), the end timeout for a CoAP message with default retransmission (maximum 4 retransmits) and exponential backoff can range from approximately 62 to 93 seconds. * 1NCE OS is currently only available through the Europe (Frankfurt), US East (N. Virginia), and Asia-Pacific (Tokyo) breakout regions. For more details, see [Internet Breakout](/docs/v2/network-services/network-services-internet-breakout/). --- # Web Interface Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-controller/device-controller-web-interface/ The device controller is available in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal, by opening the device controller tab. ## Sending Data to device On device controller page, table with the device list is shown. Filtering by Device ID (ICCID) is available in the table.
![Device controller devices table with filtering](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/devices-table-filtering.png)
By clicking on a specific device in the table a wizard will be opened that allows: * Sending UDP message to the device * Sending `POST`, `PUT`, `DELETE`, `PATCH` or `GET` CoAP request to the device. * Triggering `Read`, `Write`, `Execute`, `Observe-start` or `Observe-end` LwM2M action to the device
![Device controler UDP request creation view](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/new-request-udp.png)

Device controller UDP request creation view

### Request Mode #### Send Now Request mode `SEND_NOW` will send the data to the device immediately. It will be validated if device is currently registered to LwM2M server, if LwM2M protocol will be selected. If device is not registered to LwM2M server an error toaster will be shown.
![Device not registered to LwM2M server](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/Not-registered-to-lwm2m-server.png)
For CoAP and LwM2M messages wizard will wait for the response and display the response details.
![Device controler waiting for response](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/coap-waiting-for-response.png)

Device controller waiting for response

![LwM2M Response Details](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/LwM2M-Success-Response.png)
:::warning Please note that **Response wizard is not present for UDP messages due to UDP specifics**. ::: #### Send when device is active Request mode `SEND_WHEN_ACTIVE` will schedule the message and send the data to device when it will become active. Scheduled messages will be sent out on `Cross-protocol trigger` or `LwM2M registration and update events` as decribed in the [device controller features](/docs/v2/1nce-os/1nce-os-device-controller/device-controller-features-limitations/). In this request mode it is possible to configure `Send Attempts` for CoAP and LwM2M protocols. For failed messages [retry mechanism](/docs/v2/1nce-os/1nce-os-device-controller/device-controller-api/#retry-mechanism) will be applied if required.
![Send attempts configuration](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/send-attempts.png)
:::warning Please note that **Send attempts are NOT supported for the UDP protocol**. ::: ## Requests ### Requests history In the device controller, the tables with active and archived requests history are available. Archived request history is stored for 7 days and active request history is stored for 1 day. It is possible to filter the requests by the following parameters: * Request Id * ICCID (Device Id) * Request Status * Active requests table: (`Scheduled`, `In progress`) * Archived requests table: (`Failed`, `Succeeded` or `Canceled`) * Protocol (`UDP, CoAP` or `LwM2M`)
![Device controller requests table with filtering](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/requests-table-filtering.png)
### Request Details By clicking on a specific request the request details will be displayed. In the request details some fields are mandatory for every request. Depending on protocol and request mode some fields could be optional: #### Mandatory fields ##### Request: * Request Id * Status of the request * Protocol * Request Mode * Request Creation Time * Request Last Update Time * Request Data ##### Device: * Device Id (ICCID) * IP Address #### Optional fields * Configured send attempts * Left send attempts * Result Data
![Request details](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/request-details.png)
### Canceling a request It is possible to cancel a request form Request Details. This is possible only for "Scheduled" requests.
![Canceling a request](/img/1nce-os/1nce-os-device-controller/device-controller-web-interface/cancel-request.png)
--- # Device Inspector Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-inspector/ ![](/img/1nce-os/1nce-os-device-inspector/device-inspector.png) The 1NCE Device Inspector as part of the 1NCE OS allows customers to seamlessly manage of all SIM devices existing in the 1NCE Portal Organization. The management makes transparent use of the SIM-as-an-Identity service in the background to reference a digital representation of each individual device with a 1NCE SIM. The Device Inspector combines an interface for analytics and monitoring. Possible use cases are: * Viewing the current digital state representation of a SIM device. * Browsing through the history of states of a SIM device. * Performing analytics or monitoring activities on their devices. --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/ ## Features The device inspector overview provides a list of all customer devices. The list can be filtered by `ICCID` to search for a specific device. To see more information of a certain device, a single device can be select it in the list.
![Device Inspector overview](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-filter.png)
The details will provide more specific information. ### State Device state for UDP, CoAP or LwM2M messages. * UDP or CoAP . Last message received from the device is stored in the state. By default, the portal tries to convert Base64 messages to JSON format. If the received content is not valid JSON, the portal will display the original message as Base64. If the user has enabled the **energy saver** feature with a valid template for transforming payload into JSON, the portal will display message as a JSON and, if the message is not tranformable with the existing **energy saver** template, there will be an admin log created with the error message. For CoAP messages, the topic is also stored in the device state. * LwM2M. Digital representation from the device is stored in state according to OMA specifications.
![Device Inspector Details](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-details.png)

Device State for CoAP

#### State Auto-Refresh An auto-refresh toggle is located next to the State section title. When enabled, the device telemetry (shadow state) data refreshes automatically every 30 seconds. **When auto-refresh is active:** - The device telemetry data refreshes every 30 seconds - An informative message is displayed indicating that data refreshes every 30 seconds - The 30-second countdown starts after the previous refresh request completes ![state auto-refresh on](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-state-auto-refresh-on.png) **When auto-refresh is disabled:** - The periodic refresh stops immediately **Automatic deactivation:** - If an API error occurs during a refresh cycle, the auto-refresh toggle is automatically turned off - When you navigate away from the State tab to another Device Inspector tab, auto-refresh stops automatically The auto-refresh toggle is available on all protocol sub-tabs (UDP, CoAP, LwM2M) and remains visible even when no messages exist for the selected protocol. ![state auto-refresh off](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-state-auto-refresh-off.png) ### History Whenever messages (UDP, CoAP or LwM2M) from a device are sent to the 1NCE OS endpoint(s) those are stored for 7 days. * UDP or CoAP . Traversed messages are stored. The message format depends on the energy saver status for the specific protocol. If the [Energy Saver](/docs/v2/1nce-os/1nce-os-energy-saver/) is not enabled, then message will be converted and stored in Base64 format, but when enabled, then a processed message will be stored in JSON format. * LwM2M. Messages are stored in JSON format. More details in [Historian Web Interface](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/) or [Historian API Examples](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-historian-api/). ### Map If the device is utilizing [Device Locator](/docs/v2/1nce-os/1nce-os-device-locator/), then a location will be pinpointed on a map.
![Device Inspector Details. Map](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-map.png)
*Device location on map* ### Cell Tower Events Cell tower events show the history of cell tower-based location resolutions for selected device when Cell Tower Location is enabled.
![Device Cell Tower Events](/img/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/device-inspector-cell-tower-events.png)
## Limitations * We only show history of the device from the last 7 days, but device state is stored permanently. * History of device is not supporting messages bigger than 2048 bytes. If messages are stored in Base64 [format](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/#history), then raw binary message size shouldn't exceed 1536 bytes. * Maximum state size for each protocol (UDP, CoAP and LwM2M) is 8192 bytes. * A summary of the location of the device is shown, containing the first position, the last position and some positions inbetween (more data available via the API). * The current digital state representation of a SIM device can be updated **up to 20 times per second**. Therefore, if a given device sends messages at a higher frequency, it would cause a throttling issue resulting in the state not being updated. That is noticeable by the existence of **[DeviceShadowUpdaterThrottlingIssue]** logs in the 1NCE OS Portal Administrator Logs page. * A different issue can happen if a device sends multiple messages in a short interval. That would result in a digital state version conflict and only one of the states will be actually persisted. The existence of **[DeviceShadowUpdaterOnConflict]** represents that situation. * When auto-refresh is active in the History tab, the chart/statistics section is hidden from view. * When auto-refresh is active in the History tab, pagination is disabled — only the latest messages are shown. * The auto-refresh interval is fixed at 30 seconds and is not user-configurable. * Auto-refresh is automatically disabled when an API error occurs during a refresh cycle. --- # Historian API Examples Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-historian-api/ The Device Inspector Historian has an API to allow users to get their data without going to the portal. The full Historian API description is available in the [API Explorer](/api/). *** # Examples ## Get Messages ### Device messages (7 days) Getting all messages for a specific device for 7 days for a device with iccid `123456789012345678` would be: ```shell curl -X GET https://api.1nce.com/management-api/v1/inspect/devices/history?iccid=123456789012345678 ``` We would receive a response like: ```json { "items": [ { "time": "2022-02-21T12:47:30.085", "payload": "{\"battery\":98,\"saturation\":0.55,\"temperature\":11.6}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T12:47:24.278", "payload": "{\"battery\":99,\"saturation\":0.55,\"temperature\":11.5}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T12:47:21.495", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" } ] } ``` In the response, we can see that a device (that has ICCID “123456789012345678“ and if it has a 1NCE sim also deviceId “123456789012345678“), sent 2 UDP and 1 CoAP message. The payload in each UDP message is a JSON string because the Translation service was used. CoAP message has base64 encoded payload. These are the only messages the device was sending in 7 days because we didn’t specify time constraints and the query was using the default value. ### Messages Timerange Getting messages in the specified time range for the same device but in the time range between `2022-02-21T13:20:00.000` and `2022-02-21T13:22:00.000`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?startDateTime=2022-02-21T13:20:00.000&endDateTime=2022-02-21T13:22:00.000" ``` The response would be in a similar format as before, but the messages would only be those that were received in the requested time range: ```json { "items": [ { "time": "2022-02-21T13:21:50.268", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:41.504", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` Both of the query parameters are optional. If only `startDateTime` is provided, the query will consider the end date-time to be the current time. If only `endDateTime` is provided, the start date-time will be the time 7 days ago. ### Specifying Message Protocol The API can return messages that were sent by the device using a specific protocol (either UDP, CoAP, or LwM2M). To get only CoAP messages sent by the same device `123456789012345678` (without specific time range): ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?protocol=CoAP" ``` We would receive only messages that were sent with CoAP protocol in the last 7 days: ```json { "items": [ { "time": "2022-02-21T13:00:08.066", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" }, { "time": "2022-02-21T13:00:08.056", "payload": "dGVzdGRhdGE=", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "COAP" } ] } ``` ### Working with Pagination By default, up to 10 messages are returned from the API. The user is able to specify page size with a query parameter pageSize. The value of this parameter should be between 1 and 25. Example call to get UDP messages of the example device in the page of 3: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history?iccid=123456789012345678&protocol=UDP&pageSize=3" ``` The response would be: ```json { "items": [ { "time": "2022-02-21T13:21:50.268", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:45.480", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.1}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T13:21:44.360", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ], "nextToken": "AYAFeEdvNYWYGIwsjZX2PFMhRfoAAAA...", "firstToken": "AYAXeFiqDUzhDQ7Tvjydy4JkuuoAAAA..." } ``` We can see that there are two extra fields in the response: nextToken and firstToken. This means that there are more records to see than this. If we would pass nextToken as a query parameter, we would get the next page of data: ```shell curl -X GET "https://api.1nce.com/management-api/v1/devices/messages?iccid=123456789012345678&protocol=UDP&pageSize=3&nextToken=AYAFeEdvNYWYGIwsjZX2PFMhRfoAAAA..." ``` We would get the data: ```json { "items": [ { "time": "2022-02-21T12:47:21.495", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` In this case, there are no extra fields which means no more records to see. If we would provide `firstToken` as a `nextToken` in the query, we would get the same result as we had when we called it the first time (even if there were new messages by this time). ### Specifying Timezone For ease of dealing with time zones, we can specify them in the query. To query in scope of +2 time zone: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/123456789012345678/history?startDateTime=2022-02-21T16:20:00.000+02:00&endDateTime=2022-02-21T16:30:00.000+02:00" ``` We would get the same time zone in the response as well: ```json { "items": [ { "time": "2022-02-21T16:25:57.740", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-21T16:21:49.651", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ] } ``` ### Calling endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history" ``` We would get the last 10 messages from all devices within the last 7 days. ```json { "items": [ { "time": "2022-02-21T16:25:57.740", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T17:25:57.740", "payload": "{\"battery\":97,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T18:25:57.740", "payload": "{\"battery\":96,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-21T19:25:57.740", "payload": "{\"battery\":94,\"saturation\":0.57,\"temperature\":11.2}", "iccid": "543216789012345678", "deviceId": "543216789012345678", "protocol": "COAP" }, { "time": "2022-02-22T16:21:49.651", "payload": "{\"battery\":98,\"saturation\":0.57,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:23:49.651", "payload": "{\"battery\":98,\"saturation\":0.58,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:25:49.651", "payload": "{\"battery\":98,\"saturation\":0.59,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:27:49.651", "payload": "{\"battery\":98,\"saturation\":0.60,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:29:49.651", "payload": "{\"battery\":98,\"saturation\":0.61,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" }, { "time": "2022-02-22T16:31:49.651", "payload": "{\"battery\":98,\"saturation\":0.63,\"temperature\":11.0}", "iccid": "123456789012345678", "deviceId": "123456789012345678", "protocol": "UDP" } ], "nextToken": "AYABeJNbCVkFnuUD8Lwc.....", "firstToken": "AYABeGNSdMbKy3uSXn2Z...." } ``` ## Get Historian Insights ### Calling Historian Insights endpoint without query parameters ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/history/insights" ``` We would get a number of messages in the 1-day intervals for specific protocols for the last 7 days. ```json { "items": [ { "time": "2022-03-23T00:00:00.000", "protocol": "COAP", "amount": 1 }, { "time": "2022-03-22T00:00:00.000", "protocol": "COAP", "amount": 13 }, { "time": "2022-03-22T00:00:00.000", "protocol": "LWM2M", "amount": 27 }, { "time": "2022-03-21T00:00:00.000", "protocol": "LWM2M", "amount": 1 }, { "time": "2022-03-21T00:00:00.000", "protocol": "UDP", "amount": 1 }, { "time": "2022-03-18T00:00:00.000", "protocol": "LWM2M", "amount": 62 }, { "time": "2022-03-18T00:00:00.000", "protocol": "UDP", "amount": 1 }, { "time": "2022-03-17T00:00:00.000", "protocol": "LWM2M", "amount": 2 } ], "interval": "1d" } ``` --- # Historian Web Interface Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/ To see the Data Historian in the [1NCE OS](https://portal.1nce.com/portal/customer/1nceos), open the Device Inspector and select a device. The device History is presented like this chart: ![daily device history](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_1_day.png) On the horizontal axis, we can see the dates or hours, depending on if we selected the last day or the last 7 days. On the vertical axis, there is the total message amount per day/hour. The bars are split into multiple colored sections. Each section represents message count by a specific source protocol (UDP, CoAP, or LwM2M). The user can toggle protocols shown by clicking on the protocol labels under the chart. In the picture above, we have the last 1 day selected. At 11 AM, there were 4 CoAP messages and 4 LwM2M messages sent by this device. To see the message payload details, click on the colored bar of the required protocol. The latest LwM2M message sent by the device at 5:09:32 PM is shown, and its payload is visible and can be quickly copied by clicking the copy button. We can cycle through the individual payloads by clicking the “Previous” and “Next” buttons.\ By default, the portal tries to convert Base64 messages to JSON format. If the received content is not valid JSON, the portal will display the original message as Base64. If the user has enabled the **energy saver** feature with a valid template for transforming payload into JSON, the portal will display message as a JSON and, if the message is not tranformable with the existing **energy saver** template, there will be an admin log created with the error message. As mentioned, we can see the messages statistics of the last 7 days as well when we change the period selector above the chart: ![weekly device history](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_7_days.png) ## Refreshing Data The History tab provides controls to refresh message data without reloading the entire page. You can trigger a one-time refresh or enable automatic periodic refresh. ### Manual Refresh Button The History tab displays a refresh button in the messages/payload section header. Clicking it refreshes only the messages and payload data shown below the button — the chart statistics above are not re-fetched. This is useful when you want to check for new messages without affecting the chart view or your current filter selections. ![manual history refresh](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_manual_refresh.png) ### Auto-Refresh Toggle An auto-refresh toggle is located in the messages section header of the History tab. When enabled, the messages section refreshes automatically every 30 seconds, providing near-real-time monitoring of incoming device messages. **When auto-refresh is active:** - The chart/statistics section is hidden from view - The pagination buttons (Previous/Next) are disabled - An informative message is displayed explaining that data refreshes every 30 seconds, navigation buttons are disabled, and the latest message is always shown regardless of previous filter or graph selections - The 30-second countdown starts after the previous refresh request completes (not on a fixed wall-clock schedule), so the actual interval between refreshes is 30 seconds plus the request duration - The first automatic refresh occurs 30 seconds after enabling the toggle — the current data is shown immediately ![history auto-refresh](/img/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/device_history_auto_refresh.png) **When auto-refresh is disabled:** - The periodic refresh stops immediately - The chart section reappears - Pagination buttons become active again **Automatic deactivation:** - If an API error occurs during a refresh cycle, the auto-refresh toggle is automatically turned off - When you navigate away from the History tab to another Device Inspector tab, auto-refresh stops automatically The auto-refresh toggle is visible even when the messages section has no data (empty state), so you can enable it before messages arrive. --- # Device Integrator Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-integrator/
![Device Integrator as part of the IoT Integrator](/img/1nce-os/1nce-os-device-integrator/IoT-Integrator.png)
The Device Integrator supports connecting devices to 1NCE OS managed services. For that we offer multiple protocols that can be used and tested in the 1NCE OS: UDP, CoAP and LwM2M. The available devices can be found in the [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/). To establish connection we provide special domain names for each protocol. Each domain name resolves to two IP addresses. Those IPs can also be cached on the embedded device if necessary, but we do not guarantee that those IPs will always stay the same. So it is suggested to always have fallback DNS resolvement implemented at some point or at least when connection error occurs. The supported protocols are UDP, CoAP and LwM2M and the connection info is visible in the 1NCE OS frontend. Further information about these protocols can be found in the subpages and the LwM2M chapter: * [UDP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-udp/) * [CoAP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/) * [LwM2M](/docs/v2/1nce-os/1nce-os-lwm2m/) **Note:** 1NCE OS is currently only available through the Europe (Frankfurt), US East (N. Virginia), and Asia-Pacific (Tokyo) breakout regions. For more details, see [Internet Breakout](/docs/v2/network-services/network-services-internet-breakout/). --- # CoAP Code Examples Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/ # CoAP Code Examples This page provides runnable Node.js code examples for testing the 1NCE OS CoAP endpoints. All examples use the [`node-coap-client`](https://www.npmjs.com/package/node-coap-client) library version 1.0.9. ## Prerequisites Install the dependency: ```bash npm install node-coap-client@1.0.9 ``` :::tip On environments where native compilation fails (e.g., Termux/Android), you can install with `--ignore-scripts` since the native crypto module is not used on Node.js >= 10. ::: ## Sending CoAP Messages (POST) The following script demonstrates sending telemetry data via CoAP POST, with optional DTLS encryption. ```javascript const coap = require("node-coap-client").CoapClient; /////// Here you can define if you want to enable or disable DTLS requests /////// const dtlsEnabled = true; // (optional) Enable/Disable DTLS ////////////////////////////////////////////////////////////////////////////////// async function coapOnboard(url) { await tryToConnectToCoapServer(url); const options = { keepAlive: true, // Whether to keep the socket connection alive. Speeds up subsequent requests confirmable: true, // Whether we expect a confirmation of the request retransmit: false, // Whether this message will be retransmitted on loss }; console.log(`Calling CoAP bootstrap endpoint ${url}`); const result = await coap.request(url, "get", options); const payload = result.payload?.toString(); if(result.code.toString() !== "2.05") { throw new Error(`Error calling CoAP bootstrap endpoint. Result code: ${result.code.toString()}, Payload: ${payload}`); } console.log(`Boostrap payload: ${payload}`); const [clientIdentity, preSharedKey, coapsEndpointUrl] = payload.split(","); console.log("==================================="); console.log("DTLS details:"); console.log(`Client Identity: ${clientIdentity}`); console.log(`Pre-shared key: ${preSharedKey}`); console.log(`Coap endpoint: ${coapsEndpointUrl}`); console.log("==================================="); return { preSharedKey, clientIdentity, coapsEndpointUrl }; } function logResponseDetails(res) { console.log("========================================================="); console.log("Server Response"); console.log("Status: " + res.code); console.log("Payload: " + res.payload.toString()); console.log("========================================================="); } function enableDtls(url, clientIdentity, preSharedKey) { coap.setSecurityParams(url, { psk: { [clientIdentity]: preSharedKey, }, }); } async function tryToConnectToCoapServer(url) { console.log("Trying to connect to CoAP server"); const res = await coap.tryToConnect(url); if (!res) { console.error("Connection failed to CoAP server"); throw Error(`Failed to connect to coap server: ${url}`); } console.log("Successfully connected to CoAP server"); } async function sendCoapMessage(url, message) { const payload = Buffer.from(message); const options = { keepAlive: true, // Whether to keep the socket connection alive. Speeds up subsequent requests confirmable: true, // Whether we expect a confirmation of the request retransmit: false, // Whether this message will be retransmitted on loss }; console.log(`Sending CoAP message to ${url}`) const result = await coap.request( url, // Server url (string) "post", // Request methos ("get" | "post" | "put" | "delete") payload, // Request payload (buffer) options, // Request options ); logResponseDetails(result); const resultPayload = result.payload?.toString(); if (result.code.toString() !== "2.04") { throw new Error(`Error message received from CoAP server. Result code: ${result.code.toString()}, Payload: ${resultPayload}`); } return { code: result.code.toString(), message: resultPayload, }; } async function callPost(host, topic, message) { try { const protocol = dtlsEnabled ? "coaps" : "coap"; const port = dtlsEnabled ? 5684 : 5683; const url = `${protocol}://${host}:${port}/?t=${topic}`; if (dtlsEnabled) { console.log("Enabling DTLS..."); const boostrapUrl = `coap://${host}:5683/bootstrap`; const { clientIdentity, preSharedKey } = await coapOnboard(boostrapUrl); enableDtls(url, clientIdentity, preSharedKey); console.log("DTLS enabled"); } await tryToConnectToCoapServer(url); await sendCoapMessage(url, message); console.log("Coap message sent"); } catch (error) { console.error("Coap exception", error); throw error; } finally { coap.reset(); } } (async () => { const message = { timestamp: new Date().getTime(), description: "Example message", }; const host = "coap.os.1nce.com"; const topic = "sometesttopic" await callPost(host, topic, JSON.stringify(message)); })(); ``` Enable or disable the CoAP DTLS connection on line 4. By default, the script uses DTLS. ## Retrieving Device Location (GET) The following script retrieves the device location via a CoAP GET request to `/location`. ### Plain CoAP ```javascript const { CoapClient } = require("node-coap-client"); async function getLocation() { try { const url = "coap://coap.os.1nce.com:5683/location"; const options = { keepAlive: false, confirmable: true, retransmit: true, }; console.log(`Requesting location from ${url}`); const result = await CoapClient.request(url, "get", undefined, options); const code = result.code.toString(); if (code === "4.01") { console.error("Unauthorized: Device not found by source IP"); return; } if (code === "4.04") { console.error("Not Found: No location data available for this device"); return; } if (code === "4.05") { console.error("Method Not Allowed: Only GET requests are supported on /location"); return; } if (code === "5.02") { console.error("Bad Gateway: Upstream location service error"); return; } if (code === "5.04") { console.error("Gateway Timeout: Upstream location service did not respond"); return; } if (code !== "2.05") { console.error(`Unexpected response code: ${code}`); return; } const payload = result.payload.toString(); console.log(`Response payload:\n${payload}`); // Parse CSV: split on line-feed to get rows, then split data row on comma const rows = payload.split("\n"); const dataRow = rows[1]; const [Longitude, Latitude, Source, SampleTime] = dataRow.split(","); console.log("==================================="); console.log("Device Location:"); console.log(`Longitude: ${Longitude}`); console.log(`Latitude: ${Latitude}`); console.log(`Source: ${Source}`); console.log(`SampleTime: ${SampleTime}`); console.log("==================================="); } catch (error) { console.error("CoAP exception", error); throw error; } finally { CoapClient.reset(); } } (async () => { await getLocation(); })(); ``` ### DTLS Variant This variant first calls `/bootstrap` to obtain PSK credentials, then accesses the location endpoint securely. ```javascript const { CoapClient } = require("node-coap-client"); async function getLocationWithDtls() { try { const host = "coap.os.1nce.com"; // Step 1: Call /bootstrap to obtain PSK credentials const bootstrapUrl = `coap://${host}:5683/bootstrap`; console.log(`Calling CoAP bootstrap endpoint ${bootstrapUrl}`); const bootstrapResult = await CoapClient.request(bootstrapUrl, "get", undefined, { keepAlive: false, confirmable: true, retransmit: true, }); if (bootstrapResult.code.toString() !== "2.05") { throw new Error(`Bootstrap failed. Code: ${bootstrapResult.code.toString()}`); } const bootstrapPayload = bootstrapResult.payload.toString(); const [clientIdentity, preSharedKey] = bootstrapPayload.split(","); console.log("==================================="); console.log("DTLS details:"); console.log(`Client Identity: ${clientIdentity}`); console.log(`Pre-shared key: ${preSharedKey}`); console.log("==================================="); // Step 2: Set DTLS security params and request location const locationUrl = `coaps://${host}:5684/location`; CoapClient.setSecurityParams(locationUrl, { psk: { [clientIdentity]: preSharedKey, }, }); const options = { keepAlive: false, confirmable: true, retransmit: true, }; console.log(`Requesting location from ${locationUrl}`); const result = await CoapClient.request(locationUrl, "get", undefined, options); const code = result.code.toString(); if (code === "4.01") { console.error("Unauthorized: Device not found by source IP"); return; } if (code === "4.04") { console.error("Not Found: No location data available for this device"); return; } if (code === "4.05") { console.error("Method Not Allowed: Only GET requests are supported on /location"); return; } if (code === "5.02") { console.error("Bad Gateway: Upstream location service error"); return; } if (code === "5.04") { console.error("Gateway Timeout: Upstream location service did not respond"); return; } if (code !== "2.05") { console.error(`Unexpected response code: ${code}`); return; } const payload = result.payload.toString(); console.log(`Response payload:\n${payload}`); // Parse CSV: split on line-feed to get rows, then split data row on comma const rows = payload.split("\n"); const dataRow = rows[1]; const [Longitude, Latitude, Source, SampleTime] = dataRow.split(","); console.log("==================================="); console.log("Device Location:"); console.log(`Longitude: ${Longitude}`); console.log(`Latitude: ${Latitude}`); console.log(`Source: ${Source}`); console.log(`SampleTime: ${SampleTime}`); console.log("==================================="); } catch (error) { console.error("CoAP exception", error); throw error; } finally { CoapClient.reset(); } } (async () => { await getLocationWithDtls(); })(); ``` --- # CoAP Endpoint Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/ ## CoAP Overview The CoAP Endpoint `coap://coap.os.1nce.com:5683` hosts a POST endpoint on the server root path (`/`) or on the `/data` path if device firmware for some reason cannot send to the root path. The endpoint supports both normal, non-translatable messages and translatable messages by using the Energy Saver, with a safe payload size of up to 1024 bytes. The POST endpoint takes an optional query parameter (or Location-Query) `t` to provide the MQTT topic used for forwarding this message to an MQTT broker (e.g., `coap://coap-service:5683/?t=topicName` or `coap://coap-service:5683/data?t=topicName`). The Location-Query is limited to 255 characters by the CoAP protocol, hence the topic name itself can only contain up to 253 characters (`t` and `=` also count as characters). The topic name can only contain alphanumeric characters, underscores, and forward slashes (no two slashes in a row). If these constraints are violated, a Bad Request (4.00) will be returned. If a targeted device could not be found or is in a non-active status, the CoAP service will return an Unauthorized (4.01) response and no further processing of the message will take place. ## CoAP Communication While using UDP protocol for transport, the CoAP protocol offers reliable communication by using a message confirmation mechanism. Each CoAP request has to be acknowledged by the server, so that the client can be sure that the message was processed:
![CoAP reliable messaging](/img/1nce-os/1nce-os-device-integrator/device-integrator-coap/coap-con.png)
There are a few key moments that allow reliable communication: 1. To maximize the chance that the message succeeds even in a lossy network environment, CoAP has a retransmission mechanism. The client re-sends the Confirmable message (`CON`) until the Acknowledgement (`ACK`) is received or the *exchange lifetime* has ended. The total exchange lifetime (`EXCHANGE_LIFETIME`) is the time from starting to send a Confirmable message to the time when an acknowledgment is no longer expected.\ By default, the `EXCHANGE_LIFETIME` value is `247 seconds`. 2. CoAP messages contain a *Message ID* (also known as `MID`) to detect duplicates due to retransmissions. The Message ID has to be unique during the `EXCHANGE_LIFETIME`, so the client's endpoint should be able to specify a unique `MID` value if messages are being sent often enough. Most high-level CoAP clients manage `MID` uniqueness internally, but for low-level clients like the *Quectel BG95* modem, it can be specified in the AT command as `msgID`: ```text AT+QCOAPHEADER=,,[,,] ``` There are two examples of the retransmission situation in a single exchange lifetime: * The client's `CON` message did not reach the server. The client resends the same `CON` message with the same `MID`. * The server's `ACK` message did not reach the client. The client resends the same `CON` message with the same `MID` (because there was no acknowledgment). The server responds with the same `ACK` because it sees the already-processed `MID` and does not process the request again. ## DTLS Encryption for CoAP
![CoAP DTLS Support](/img/1nce-os/1nce-os-device-integrator/device-integrator-coap/coap-onboarding.png)
Ensuring data is securely sent from a device to 1NCE OS is an important part of gaining customer trust. To provide this secure connection, 1NCE OS has implemented a DTLS layer in the CoAP communication from the device to 1NCE OS. This allows the device to securely send its data without the possibility of messages being read or modified along the way. The diagram above describes this process. First, when the device is ready to onboard itself, it calls the CoAP bootstrapping endpoint. This retrieves the necessary DTLS credentials to onboard securely and initialize the CoAP connection using a PSK. To utilize DTLS encryption with 1NCE OS, a pre-shared key (PSK) is essential for securing data. This key encrypts and decrypts transmitted data. Devices can connect securely using CoAP with DTLS by accessing the endpoint `coaps://coap.os.1nce.com:5684` or `coaps://coap.os.1nce.com:5684/data`. To retrieve the PSK, send a GET request to `coap://coap.os.1nce.com:5683/bootstrap`. This endpoint will return an existing key, or if none is available, it will generate and provide a new one. Additionally, you can manually set the PSK (in plaintext or HEX format): * Through the 1NCE OS API endpoint described in [API Explorer](/api/1nce-os/create-pre-shared-device-key/). * In the 1NCE OS portal Device Integrator when [testing the CoAP endpoint](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/#testing-the-endpoint). ### DTLS Bootstrapping Information The pre-shared key is valid indefinitely. If the bootstrapping is called 5 or more minutes after the last time bootstrapping was called and the pre-shared key was not set previously by the user, the pre-shared key will be regenerated with a new value. | Name | Type | Description | | :------------- | :----- | :------------------------------------------------------------------ | | clientIdentity | string | The ICCID of the device SIM | | preSharedKey | string | A pre-shared key the device can use to authenticate itself on DTLS | | coapsEndpointUrl | string | The CoAPS endpoint URL for DTLS-encrypted communication | **Example response:** ```text 8988280666000000000,aB3dEf7hIjKlMnOp,coaps://coap.os.1nce.com:5684 ``` For a complete runnable example of sending CoAP messages (with optional DTLS), see the [CoAP Code Examples](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/#sending-coap-messages-post) page. ## Location Endpoint The Location Endpoint at path `/location` allows IoT devices to retrieve their last known geographic position. The device is identified using the [SIM-as-an-Identity](/docs/v2/1nce-os/1nce-os-device-authenticator/#sim-as-an-identity) principle and supports only the GET method. Non-GET requests receive a CoAP 4.05 (Method Not Allowed) response. The endpoint is accessible via: - Plain CoAP: `coap://coap.os.1nce.com:5683/location` - DTLS-encrypted CoAPS: `coaps://coap.os.1nce.com:5684/location` ### Response Format A successful request returns a CoAP 2.05 (Content) response with Content-Format set to text/plain. The response body is formatted as CSV with a comma (`,`) delimiter and line-feed (`\n`) line ending. The first row is a header line with column names. **Response information model:** | Name | Type | Description | | :--- | :--- | :---------- | | Longitude | string (decimal degree numeric) | Geographic longitude of the device | | Latitude | string (decimal degree numeric) | Geographic latitude of the device | | Source | string | Identifier of the location source (e.g., [GPS](/docs/v2/1nce-os/1nce-os-device-locator/#gps-location), [CellTower](/docs/v2/1nce-os/1nce-os-device-locator/#cell-tower-location)) | | SampleTime | string (integer EPOCH seconds) | Timestamp of the location measurement in seconds since 1970-01-01 UTC | **Example response:** ```text Longitude,Latitude,Source,SampleTime 13.404954,52.520008,GPS,1700000000 ``` ### Authentication The device is authenticated by source IP address lookup. The CoAP server resolves the device identity from the requesting IP address. Devices can access the Location Endpoint via plain CoAP (`coap://coap.os.1nce.com:5683/location`) or securely via DTLS-encrypted CoAPS (`coaps://coap.os.1nce.com:5684/location`) using a PSK obtained from the `/bootstrap` endpoint. For details on obtaining PSK credentials for DTLS encryption, see the [DTLS Encryption for CoAP](#dtls-encryption-for-coap) section. If the source IP address does not match any registered device, the endpoint returns CoAP 4.01 (Unauthorized). ### Response Codes The following table lists all response codes returned by the Location Endpoint: | Code | Description | Payload | | :--- | :---------- | :------ | | 2.05 | Content — Successful response with CSV location data | CSV location data | | 4.00 | Bad Request — Invalid request | Empty | | 4.01 | Unauthorized — Device not recognized | Empty | | 4.03 | Forbidden — Access denied | Empty | | 4.04 | Not Found — No location data available for the device | Empty | | 4.05 | Method Not Allowed — Non-GET request sent to the endpoint | Empty | | 5.02 | Bad Gateway — Service temporarily unavailable | Empty | | 5.04 | Gateway Timeout — Service did not respond in time | Empty | All error responses (4.xx and 5.xx) return an empty payload. For runnable examples of retrieving device location (plain CoAP and DTLS), see the [CoAP Code Examples](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap-testing/#retrieving-device-location-get) page. ## CoAP Endpoint Information Base URL: `coap.os.1nce.com`\ Protocol: CoAP(s)\ Supported Paths: - `/` or `/data` — for telemetry data - `/bootstrap` — for DTLS bootstrapping - `/location` — for device location retrieval (GET only) ### Response Codes | Code | Description | Payload | | :--- | :---------- | :------ | | 2.04 | Changed — Telemetry data accepted (`/` and `/data`) | Empty | | 2.05 | Content — Successful response | `/bootstrap`: CSV with clientIdentity, preSharedKey, coapsEndpointUrl; `/location`: CSV with Longitude, Latitude, Source, SampleTime | | 4.00 | Bad Request — Invalid request | Empty | | 4.01 | Unauthorized — Device not recognized | Empty | | 4.03 | Forbidden — Access denied | Empty | | 4.04 | Not Found — No data available for the device | Empty | | 4.05 | Method Not Allowed — Unsupported method for the path | Empty | | 5.00 | Internal Server Error | Empty | | 5.02 | Bad Gateway — Service temporarily unavailable | Empty | | 5.04 | Gateway Timeout — Service did not respond in time | Empty | ## Features & Limitations ### Features - Reliable messaging via CoAP confirmable messages with retransmission - DTLS encryption for secure data transport using pre-shared keys - Telemetry data forwarding to MQTT brokers via topic query parameter - Device location retrieval via GET `/location` (plain CoAP and DTLS) - Automatic device authentication via [SIM-as-an-Identity](/docs/v2/1nce-os/1nce-os-device-authenticator/#sim-as-an-identity) ### Limitations The main limitation of DTLS is the use of the UDP protocol. The major drawbacks of using UDP are having to deal with packet reordering, loss of datagrams, and data larger than the size of a datagram network packet. --- # Test Endpoints Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/ ## Testing the endpoint It is possible to test the integration directly in the 1NCE portal. To do so, data should be sent to the desired endpoint: 1. _Test Integration_ should be selected for the desired protocol. 2. Device ID (ICCID) should be provided, from which the data is expected. 3. If required for CoAP & LwM2M, DTLS Pre-Shared Key can be configured in HEX or Plain-text format. 4. After clicking _Test Integration_, portal will wait for data to arrive from the device. 5. If data was sent successfully, a message will be displayed in JSON form for LwM2M messages, or if [Energy Saver Template](/docs/v2/1nce-os/1nce-os-energy-saver/) is being used for CoAP, UDP. The message will be displayed in base64 format if Energy saver is not being used.
![Test Integration Form for CoAP](/img/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/test-integration.png)
![Message received](/img/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/device-integrator-message-received.png)
### Troubleshooting Troubleshooting might be required if testing the endpoint fails (i.e., the message is not received). #### Breakout Region 1NCE OS is currently only available through the Europe (Frankfurt), US East (N. Virginia), and Asia-Pacific (Tokyo) breakout regions. For more details, see [Internet Breakout](/docs/v2/network-services/network-services-internet-breakout/). #### Energy Saver If an invalid [Energy Saver Template](/docs/v2/1nce-os/1nce-os-energy-saver/) is enabled, data will not be processed. Please validate that no errors are found in the [Admin Logs](/docs/v2/1nce-os/1nce-os-admin-logs/) related to the Energy Saver. If errors from the Energy Saver are found in the Admin Logs, please disable the Energy Saver Template for the protocol and try again. --- # UDP Endpoint Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-udp/ The UDP Endpoint receives packets sent by the customer's IoT devices with a maximum safe payload size of 508 bytes, enriches them with identifier data from the core network and forwards data to the customer's configured backend application via the Data Broker. The following address has to be used to send UDP Messages `udp://udp.os.1nce.com:4445`. A simple script to send UDP packets to the server will look like this (generic example in NodeJS): ```javascript const dgram = require('dgram'); const message = Buffer.from('Hello World'); const client = dgram.createSocket('udp4'); client.send(message, 4445, 'udp.os.1nce.com', (err) => { if (err) console.err(err); client.close(); return 'done'; }); ``` All active SIMs from an organization will be able to successfully publish messages via the UDP Endpoint, if [Terms of Use](https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf) & [Data Processing Agreement](https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf) are accepted. The incoming messages can be found in [historian web interface](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-historian-web-interface/). All TELEMETRY\_DATA events which are forwarded to the AWS IoT Core are sent to a device-specific topic with the following format for UDP and LwM2M:\ **\{iccid}/messages** For CoAP:\ **\{iccid}/\{coap\_topic}** or **\{iccid}** if no topic provided (see optional query parameter in [CoAP overview](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/)) This will result in a nicely formatted JSON-message that is also human-readable: ## Example Implementation for UDP Endpoint The following example uses Python 3.8: ```python import socket import logging import sys def send_udp_message(host, port, message): logging.basicConfig(level=logging.INFO, stream=sys.stdout, format='%(asctime)s %(levelname)s: %(message)s') logger = logging.getLogger(__name__) logger.info("Opening UDP Socket") udp_socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) try: logger.info("Sending UDP message to {}:{} with body {}".format(host,port,message)) udp_socket.sendto(message.encode(), (host, port)) logger.info("Sent UDP Message to the UDP Broker") except Exception as e: logger.error("Error sending UDP message:", e) finally: udp_socket.close() send_udp_message("udp.os.1nce.com", 4445, "Hello, UDP. Can you hear me?") ``` UDP is the most lightweight transport protocol and can easily be based on a simple socket connection as shown in the previous example. --- # Device Locator Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/
![](/img/1nce-os/1nce-os-device-locator/device-locator.png)
## Overview 1NCE OS provides the ability to manage and view device positions using both the API and the frontend. An interactive map showing all customer devices is available on the Device Locator page, and the location history of individual devices over the last 7 days can be accessed on the Device Inspector page. 1NCE OS utilizes and processes multiple sources of device location data: * GPS data via the Energy Saver template. * GPS data via LwM2M using the /6/0/0 object. * Cell tower location data using SIM network tower connections. ## Cell Tower Location The Device Locator provides an approximate position of IoT devices by analyzing data from network events when creating a new PDP Context/Session used for data transmission. This feature has to be activated in the portal. To view latest particular device cellTower location resolution attempts [Activity endpoint](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity) can be used.
![Enabling the Cell Tower location feature](/img/1nce-os/1nce-os-device-locator/enabling-cell-tower-location.png)
:::info Terminology The Cell Tower Location feature offers two solver modes: - **Basic** — included by default at no extra cost. Resolves locations using open cell tower databases. - **Plus** — a paid upgrade requiring [Device Location Credits](#device-location-credits). Provides higher accuracy and broader coverage for 3G, 4G, and LTE-M. When Plus is enabled, it can operate in two configurations: - **DEFAULT** — all devices share the same resolution frequency (once per hour). - **CUSTOM** — per-device resolver and frequency control (60–1440 minutes), managed via the API or the Plus Resolution tab in the portal. See [Per-device configuration (CUSTOM mode)](#per-device-configuration-custom-mode). DEFAULT and CUSTOM are modes within the Plus solver — they do not apply to Basic mode. ::: ### Basic mode By default, the Basic solver mode is enabled, which delivers device positioning when connected via 2G technology. Resolved position is based on the location of the cell tower device is connected to. Positioning for 3G, 4G, LTE-M, and NB-IoT connections is not guaranteed and may not be resolved. Creative Commons License OpenCelliD Project is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License ![](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) ### Plus mode When Plus solver mode is enabled, it improves the Cell Tower Location accuracy and coverage particularly for 3G, 4G and LTE-M. However, NB-IoT resolutions will not be performed in Plus solver mode. Up to 95% of all cell tower locations are successfully resolved using the Plus solver mode. New metadata field is also added with accuracy data. In the following example, the circle around the point on the map indicates that there is a 68% probability that the device is within a 270-meter radius of the provided location.
![Enabled Advanced solver mode with credits available](/img/1nce-os/1nce-os-device-locator/plus-mode.png) *Enabled Plus solver mode with credits available*
![Advanced solver mode](/img/1nce-os/1nce-os-device-locator/cell-tower-location.png) *Plus solver mode*
#### Device Location Credits Each cell tower resolution consumes 1 credit from the Device Locator credit balance. The credit balance is refreshed periodically throughout the day. If all credits are depleted or the current date reaches the credit expiry date, the Plus solver mode automatically switches to Basic mode. You can request access to this feature via the 1NCE OS portal. Credits can be purchased via the Orders tab in the 1NCE Portal by choosing the required quantity of "Whereabouts – Device Location" credits. #### Per-device configuration (CUSTOM mode) When Cell tower Plus is first enabled, it runs in DEFAULT mode — cell tower location data is resolved no more frequently than once an hour for all devices in your organization. CUSTOM mode lets you override this by configuring Cell tower Plus on a per-device basis, enabling Plus location resolution only for selected devices with individually configurable frequency intervals (60–1440 minutes). All other devices without a frequency configuration fall back to the Basic resolver. Per-device Plus resolution can also be configured through the Plus Resolution tab in the portal. For a step-by-step guide on switching to CUSTOM mode, enabling and disabling Cell tower Plus for individual devices, and querying per-device settings, see [Per-device Cell tower Plus](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/). ### Cell Tower Events The Cell tower events tab displays the history of cell tower-based location resolution attempts for a selected device. For the full field reference, the Network Event Resolver walkthrough, usage limits, and restrictions, see [Cell Tower Events](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/). ## GPS Location ### Via Energy Saver If the Energy Saver with `custom_type` in the JSON-Template is used, the location from the device can be obtained over the Energy Saver output. Visit [Energy Saver](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/) for more details. ```json { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` ### Via LwM2M If LwM2M is used, the following Resource Addresses can be used to provide the device location: `/6/0/0` (latitude, Float), `/6/0/1` (longitude, Float) and `/6/0/5` (timestamp, Time). Visit our [LwM2M Service Documentation](/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/) for more details on integrating LwM2M with the device locator. ## Geofencing The Geofencing Service allows setting virtual boundaries for devices. If a device is crossing a geofence (entering or exiting, configurable), a [geofence event](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/#geofence) will be generated and sent to the customer's Cloud Integrator Webhook integration or the AWS Integration. To start using Geofencing you need to purchase "Whereabouts - Geofencing" [credits](/docs/v2/1nce-os/1nce-os-device-locator/#geofence-credits) first. You can use following [Get customer settings](/api/1nce-os/get-customer-settings/) API endpoint to check if credits are already assigned to you. Once the credits are available, you can create your first geofence using the [Create Geofence](/api/1nce-os/create-geofence/) API endpoint. For additional info about Geofence creation use following [page](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/). Main use cases for geofencing are: * Notify user in case if a device or an object this device is attached to exits specific area. * Notify user in case if a device or an object this device is attached to enters specific area. ### Geofence Credits Each location event sourced from cell towers or GPS is evaluated against associated geofences in the 1NCE OS. If at least one geofence is evaluated for a potential breach, then one Geofencing credit is consumed. The Geofencing credit balance is refreshed periodically throughout the day. Additional credits can be purchased via the Orders tab in the 1NCE Portal by selecting the required quantity of "Whereabouts – Geofencing" credits. If all credits are depleted or expired then the Geofencing feature is automatically turned off, which means the following: * you will no longer receive exit or enter [geofence events](/docs/v2/1nce-os/1nce-os-cloud-integrator/#geofence-events) via your Cloud Integration if the device breaches any existing geofence. * you will not be able to create any new Geofences, only update or delete existing ones. * existing Geofences and associated latest device enter or exit events will continue to exist in passive mode until extra credits are purchased.
![Geofence Credits](/img/1nce-os/1nce-os-device-locator/geofencing-credits.png) *Geofence Credits*
## Disclaimer I acknowledge that activating the location feature involves processing nearby Cell Tower data by 1NCE. 1NCE processing of data is done anonymously. I understand that if the use of the service by me makes it linkable to individuals, additional data related responsibilities may apply. As per [1NCE General Terms and Conditions (GTC)](https://1nce.com/wp-content/1NCE-business-terms-EN.pdf), I am solely responsible for complying with Data Protection laws and regulations and obtaining necessary consents. --- # Per-device Cell tower Plus Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/ ## Prerequisites - **Authentication** — Bearer token required. See [authorization flow](/api/authorization/authorization/). - **Device Location Credits** — Active [Device Location Credits](/docs/v2/1nce-os/1nce-os-device-locator/#device-location-credits) must be available in your account. - **API rate limits** — Review the [rate limits](/api/api-rate-limits/) to avoid throttling. ## Understanding Cell tower Plus Modes :::info Terminology **Basic** and **Plus** are the two solver modes for Cell Tower Location. Basic is free. Plus is a paid upgrade (requires [Device Location Credits](/docs/v2/1nce-os/1nce-os-device-locator/#device-location-credits)) offering higher accuracy for 3G/4G/LTE-M. The **DEFAULT** and **CUSTOM** configurations described below apply only to the Plus solver mode. ::: The Cell tower Plus setting can be in one of the following states: - **DEFAULT** — Cell tower Plus applies uniformly to all devices — cell tower location data is resolved no more frequently than once an hour. This is the initial mode when the feature is first enabled. - **CUSTOM** — You control which devices have their network events processed with the Plus solver, and how frequently (60–1440 minutes). The frequency determines the minimum interval at which network events from a device are picked up for location resolution. All other devices fall back to basic resolution. | Organization mode | Devices with frequency set | Other devices | |---|---|---| | **DEFAULT** | All devices: Plus resolution once per hour | All devices: Plus resolution once per hour | | **CUSTOM** | Plus resolution at configured frequency | Basic resolution only (once per hour) | | **Disabled (no purchased credits)** | Basic resolution only (once per hour) | Basic resolution only (once per hour) | :::warning When using the API, switching to CUSTOM mode is required before enabling or disabling Cell tower Plus on individual devices. Attempting per-device operations without CUSTOM mode active results in a **403 Forbidden** response. In the portal, the switch to CUSTOM mode happens automatically when you save the first per-device configuration — no manual step is needed. ::: ## Portal — Plus Resolution Tab The Plus Resolution tab is the fourth tab on the Device Locator page. It is always visible in the navigation regardless of the Cell tower Plus setting state. ### Tab States - **Disabled state** — When Cell tower Plus is not enabled or Device Location Credits are exhausted, the tab shows an informative message with a "View documentation" link. The full tab content is not accessible until Cell tower Plus is enabled for the customer. - **Enabled state** — When Cell tower Plus is enabled and credits are available, the tab renders the Mode Dropdown, Manage SIMs section, and Enabled SIMs Table.
![Plus Resolution tab in disabled state](/img/1nce-os/1nce-os-adl-per-device/disabled.png) *Plus Resolution tab — disabled state*
A page-level refresh re-checks the Cell tower Plus setting state. ### Batch Processing and Progress When a batch operation is submitted, the portal divides the selected SIMs into sequential chunks of 100 and processes each chunk one at a time. A progress indicator is displayed during processing. - **Full success** (zero failures) — A success toastr notification is displayed and the Enabled SIMs Table refreshes automatically. - **HTTP error** — A toastr error notification is displayed. - **Partial failure** — The Result Modal opens showing success/failure counts and the list of failed ICCIDs with a download button.
![Result Modal showing success and failure counts with failed ICCIDs](/img/1nce-os/1nce-os-adl-per-device/partial_success.png) *Result Modal — partial failure with downloadable failed ICCID list*
:::info The 100-device chunk size is a fixed system limit. For large CSV uploads, the portal handles chunking automatically. ::: ## Workflow ### Step 1 – Switch to CUSTOM Mode Patch the Cell tower Plus setting with `{"mode": "CUSTOM"}` to enable per-device configuration. **Endpoint:** [`PATCH /v1/settings/1nceos/ADVANCED_CELL_TOWER_LOCATION/details`](/api/1nce-os/patch-setting-details/) [API example](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#switch-to-custom-mode) #### Via the Portal In the Plus Resolution tab, select **"Specific SIMs"** from the "Use Plus resolution for" dropdown. The actual mode transition does not happen when the dropdown is changed — it occurs silently in the background when you save the first per-device configuration via the Manage SIMs section.
![Mode dropdown set to All with informational message in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/All_sims.png) *Plus Resolution tab showing the "Use Plus resolution for" dropdown*
:::warning Switching from "Specific SIMs" (CUSTOM) back to "All" (DEFAULT) is not available through the portal. ::: ### Step 2 – Enable Cell tower Plus for Devices Enable Plus resolution for selected devices by providing their ICCIDs and a frequency value. **Endpoint:** [`POST /v1/locate/devices/settings`](/api/1nce-os/enable-adl-device-location-settings/) [API example](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#enable-cell-tower-plus-for-devices) #### Via the Portal In the Plus Resolution tab, expand the **Manage SIMs** section and select **"Create/Update"** from the Operation dropdown. Choose a SIM selection method: - **Single ICCID** — enter a single 19-digit ICCID - **ICCID Range** — provide start and end ICCIDs (max 100 devices) - **ICCID Ranges CSV** — upload a CSV file (up to 200 KB) with comma- or semicolon-separated ICCIDs Enter the desired frequency (60–1440 minutes) and click **Save**.
![Manage SIMs section with Single ICCID selection and frequency input in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/single_iccid.png) *Create/Update operation with Single ICCID selection*
### Step 3 – Query Per-Device Settings Retrieve which devices have per-device Cell tower Plus enabled. **Endpoint:** [`GET /v1/inspect/devices/settings/DEVICE_ADL`](/api/1nce-os/get-per-device-settings/) [API example](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#get-per-device-settings) #### Via the Portal In the Plus Resolution tab, the **Enabled SIMs Table** displays all devices with per-device Plus resolution enabled. The table shows two columns: Device ID (ICCID) and Frequency. Use the collapsible **Filters** section to filter by ICCID, and the page size dropdown ("Show N SIMs per page") to control how many rows are displayed. The table supports pagination with up to 50 pages.
![Enabled SIMs Table with ICCID filter applied and pagination controls in the Plus Resolution tab](/img/1nce-os/1nce-os-adl-per-device/Filtered_table.png) *Enabled SIMs Table with filters and pagination*
### Step 4 – Update Device Frequency Update the resolution frequency for devices that already have Cell tower Plus enabled. Use the same endpoint and method as enabling — submitting an existing ICCID with a new frequency value overwrites the previous configuration. **Endpoint:** [`POST /v1/locate/devices/settings`](/api/1nce-os/enable-adl-device-location-settings/) [API example](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#enable-cell-tower-plus-for-devices) #### Via the Portal There are two ways to update device frequency in the portal: **Bulk update via Manage SIMs section** — In the Plus Resolution tab, expand the **Manage SIMs** section with **"Create/Update"** selected, enter the target ICCIDs using any SIM selection method, provide the new frequency value, and click **Save**. Devices that already have Plus enabled will have their frequency updated to the new value. **Row-level edit from the Enabled SIMs Table** — Click the edit (pencil) icon on any row in the Enabled SIMs Table. The Edit Frequency Modal opens pre-populated with the current value. Enter the new frequency (60–1440 minutes) and confirm.
![Edit Frequency modal with pre-populated frequency value](/img/1nce-os/1nce-os-adl-per-device/edit_frequency.png) *Edit Frequency modal — update the resolution frequency for a single device*
### Step 5 – Disable Cell tower Plus for Devices Disable Plus resolution for selected devices. **Endpoint:** [`DELETE /v1/locate/devices/settings`](/api/1nce-os/disable-adl-device-location-settings/) [API example](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#disable-cell-tower-plus-for-devices) #### Via the Portal There are two ways to disable Plus resolution for devices in the portal: **Bulk delete via Manage SIMs section** — In the Plus Resolution tab, expand the **Manage SIMs** section and select **"Delete"** from the Operation dropdown. Choose a SIM selection method (Single ICCID, ICCID Range, or ICCID Ranges CSV), enter or upload the target ICCIDs, and click **Save**. The frequency input is not shown for delete operations.
![Delete operation in the Manage SIMs section with CSV upload showing parsed ICCID count](/img/1nce-os/1nce-os-adl-per-device/delete_batch.png) *Delete operation with CSV upload showing parsed ICCID count*
**Row-level delete from the Enabled SIMs Table** — Click the trash icon on any row in the Enabled SIMs Table. A confirmation modal asks "Are you sure you want to remove this SIM from Plus resolution?" with **Cancel** and **Remove** buttons.
![Row-level delete confirmation modal asking to remove a SIM from Plus resolution with Cancel and Remove buttons](/img/1nce-os/1nce-os-adl-per-device/delete_table_button.png) *Row-level delete confirmation modal*
## Additional Behavior - **New SIMs** — When a new SIM is activated in CUSTOM mode, it defaults to basic resolution. You must explicitly enable it via the POST endpoint or via the Manage SIMs section in the portal. - **Credits exhausted** — The system falls back to the Basic resolver. Mode and per-device configurations remain intact, and Plus resolution resumes automatically when credits are replenished. Purchase additional credits via the **Orders** tab in the 1NCE Portal ("Whereabouts – Device Location"). - **Credit debt** — Deducted from the next batch of purchased credits. - **Switching back to DEFAULT** — Not available via the API or the portal. When the switch is performed, all per-device frequency configurations are permanently removed. ## Related Resources - [API Examples — Per-device Cell tower Plus](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#per-device-cell-tower-plus) - [Portal — Plus Resolution Tab](#portal--plus-resolution-tab) - [Enable ADL Device Location Settings](/api/1nce-os/enable-adl-device-location-settings/) — API Explorer - [Disable ADL Device Location Settings](/api/1nce-os/disable-adl-device-location-settings/) — API Explorer - [Get Per-Device Settings](/api/1nce-os/get-per-device-settings/) — API Explorer - [Patch Setting Details](/api/1nce-os/patch-setting-details/) — API Explorer - [Device Locator overview](/docs/v2/1nce-os/1nce-os-device-locator/) - [API rate limits](/api/api-rate-limits/) --- # API Examples Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/ :::info Authentication All Device Locator API endpoints require Bearer token authentication. See [authorization flow](/api/authorization/authorization/) for details on obtaining a token. ::: ## Cell Tower Location ### Get Device Positions Get positions of a specific device for the last 7 days. Get a list of positions for device with id `1234567890123456789`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/devices/1234567890123456789/positions" ``` The response could be `200 OK` with body: ```json { "coordinates": [ { "sampleTime": "2024-05-03T11:00:24.985Z", "coordinate": [ 24.16962242126465, 56.97812271118164 ], "source": "CellTower", "metadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 } }, { "sampleTime": "2024-05-03T02:10:17.798Z", "coordinate": [ 24.16717529296875, 56.97748947143555 ], "source": "CellTower", "metadata": { "verticalAccuracy": 577, "horizontalAccuracy": 300, "verticalConfidenceLevel": 0.68, "horizontalConfidenceLevel": 0.68 } } ], "pageAmount": 1, "page": 1 } ``` :::warning Note that `metadata` parameter with accuracy data is only available in Cell tower **Plus** mode. ::: ### Get Latest Devices Positions Get latest positions of customer devices for the last 7 days. ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/positions/latest" ``` The response could be `200 OK` with body: ```json { "coordinates": [ { "deviceId": "1234567890123456788", "sampleTime": "2024-05-07T15:40:12.703Z", "coordinate": [ 24.164257049560547, 56.974369049072266 ], "source": "GPS" }, { "deviceId": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "coordinate": [ 24.16962242126465, 56.97812271118164 ], "source": "CellTower", "metadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 } } ], "pageAmount": 1, "page": 1 } ``` :::warning Note that `metadata` parameter with accuracy data is only available in Cell tower **Plus** mode. ::: :::warning Note that only one latest position is possible for a single device independent of source: either Celltower or GPS. This means that `source` query parameter selection can lead to no latest position returned for some devices. ::: ### Get Device Activity Get Cell location resolutions for one device (maximum of last 7 days, defaults to 1 day). Both resolved and unresolved location resolution attempts are returned. Get a list of location resolutions for device with id `1234567890123456789` ordered by sampleTime DESC: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/devices/1234567890123456789/activity" ``` The response could be `200 OK` with body: ```json { "items": [ { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "towerMetadata": { "MCC": "247", "MNC": "1", "LAC": "11", "CellID": "9511" }, "towerLocation": { "longitude": 24.16962242126465, "latitude": 56.97812271118164 }, "resolutionMetadata": { "horizontalAccuracy": 1220, "horizontalConfidenceLevel": 0.68 }, "radioAccessType": "2G", "resolutionMode": "ADVANCED", "locationResolutionStatus": "SUCCEEDED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T11:00:24.985Z", "towerLocation": { "longitude": 24.16962242126465, "latitude": 56.97812271118164 }, "radioAccessType": "2G", "resolutionMode": "BASIC", "locationResolutionStatus": "SUCCEEDED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T10:00:24.985Z", "towerMetadata": { "MCC": "247", "MNC": "1", "LAC": "11", "CellID": "9511" }, "radioAccessType": "2G", "resolutionMode": "ADVANCED", "locationResolutionStatus": "FAILED" }, { "iccid": "1234567890123456789", "sampleTime": "2024-05-03T09:00:24.985Z", "radioAccessType": "2G", "resolutionMode": "BASIC", "locationResolutionStatus": "FAILED" } ] } ``` :::warning Note that `towerMetadata` and `resolutionMetadata` parameters with accuracy data and tower identifier are only available in Cell tower **Plus** mode. ::: :::warning Note that, regardless of the different radio access technology types, the `LAC` property in the `towerMetadata` object can represent `TAC`. ::: ![](https://mirrors.creativecommons.org/presskit/buttons/80x15/svg/by-sa.svg) [OpenCelliD Project](https://opencellid.org/) is licensed under a [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/) ## Settings ### Get Credit Balance Current credit balance information for **Plus** solver mode is available under ADVANCED_CELL_TOWER_LOCATION setting details. Get a list of customer settings: ```shell curl -X GET "https://api.1nce.com/management-api/v1/settings/1nceos" ``` The response could be `200 OK` with body: ```json { "items": [ { "state": "ENABLED", "details": { "credits": 100, "expiryDate": "2030-04-23T10:52:18.330Z" }, "name": "ADVANCED_CELL_TOWER_LOCATION", "description": "Improves the Cell Tower Location functionality, especially for 3G, 4G and LTE-M." } ], "page": 1, "pageAmount": 1 } ``` :::warning Note that `details` object with `credits` and `expiryDate` parameters is only available in Cell tower **Plus** mode. ::: ## Geofence ### Create geofence Create new geofence: ```shell curl -X POST "https://api.1nce.com/management-api/v1/locate/geofences" ``` The request body looks like this: ```json { "name": "Once", "eventTypes": [ "EXIT", "ENTER" ], "type": "polygon", "coordinates": [ [ [ 6.957239730898948, 50.93892367514573 ], [ 6.958509831039635, 50.93836584192053 ], [ 6.959702958010666, 50.93945723847878 ], [ 6.9596259993105605, 50.934266755623526 ], [ 6.961550428436993, 50.93431526288117 ], [ 6.961434941100492, 50.94059711468901 ], [ 6.959087148954154, 50.94059710732816 ], [ 6.957239730898948, 50.93892367514573 ] ] ], "eventSources": [ "GPS", "CellTower" ] } ``` ### Get Geofence Get details of a geofence. Get a details of geofence with id `geofence_id_1`: ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` The response could be `200 OK` with body: ```json { "id": "geofence_id_1", "name": "Once", "eventTypes": [ "EXIT", "ENTER" ], "coordinates": [ [ [ 6.95724, 50.938924 ], [ 6.95851, 50.938366 ], [ 6.959703, 50.939457 ], [ 6.959626, 50.934267 ], [ 6.96155, 50.934315 ], [ 6.961435, 50.940597 ], [ 6.959087, 50.940597 ], [ 6.95724, 50.938924 ] ] ], "type": "polygon", "eventSources": [ "GPS", "CellTower" ], "deviceId": null, "created": "2025-10-02T10:36:11.166Z", "updated": "2025-10-02T10:36:11.166Z" } ``` ### Get All Geofences Get a list of all customer geofences. ```shell curl -X GET "https://api.1nce.com/management-api/v1/locate/geofences" ``` The response could be `200 OK` with body: ```json { "items": [ { "id": "1jU_nQKeiEb_1tPt6EciD", "name": "Once", "created": "2025-09-09T07:00:58.126Z", "updated": "2025-09-09T07:00:58.126Z", "deviceId": "device123", "type": "polygon" }, { "id": "76luvK3qpxZKM136xnDNM", "name": "home", "created": "2025-09-10T12:28:20.576Z", "updated": "2025-09-10T12:28:20.576Z", "deviceId": null, "type": "polygon" } ], "page": 1, "pageAmount": 1 } ``` ### Patch Geofence Update an existing geofence You can change `eventTypes`, `eventSources` and `name` of existing geofence with id `geofence_id_1`: ```shell curl -X PATCH "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` The request body looks like this: ```json { "eventTypes": [ "ENTER", "EXIT" ], "eventSources": [ "CellTower", "GPS" ], "name": "Once2" } ``` :::warning Fields like `type`, `coordinates`, or `center` cannot be changed, instead you should delete old Geofence and create new one. ::: ### Delete Geofence Delete an existing geofence Delete geofence with id `geofence_id_1`: ```shell curl -X DELETE "https://api.1nce.com/management-api/v1/locate/geofences/geofence_id_1" ``` ## Per-device Cell tower Plus The following endpoints allow managing Cell tower Plus on a per-device basis when CUSTOM mode is active. See [Per-device Cell tower Plus](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/) for the full workflow guide. ### Switch to CUSTOM Mode Switch the `ADVANCED_CELL_TOWER_LOCATION` setting to CUSTOM mode to enable per-device configuration: ```shell curl -X PATCH https://api.1nce.com/management-api/v1/settings/1nceos/ADVANCED_CELL_TOWER_LOCATION/details \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{"mode": "CUSTOM"}' ``` The response could be `200 OK` with body: ```json { "customerId": "12345", "name": "ADVANCED_CELL_TOWER_LOCATION", "state": "ENABLED", "details": { "mode": "CUSTOM" } } ``` ### Enable Cell tower Plus for Devices Enable Plus location resolution for specific devices. Requires CUSTOM mode to be active. ```shell curl -X POST https://api.1nce.com/management-api/v1/locate/devices/settings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{ "deviceIds": ["89012345678901234567", "89012345678901234568"], "details": { "frequency": 120 } }' ``` The response could be `200 OK` with body: ```json { "changedDeviceIds": ["89012345678901234567", "89012345678901234568"] } ``` :::warning The `changedDeviceIds` array lists only devices whose state actually changed. Devices already enabled or IDs that do not belong to your organization are silently excluded. ::: ### Get Per-Device Settings Query which devices have per-device Cell tower Plus enabled: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/settings/DEVICE_ADL?page=1&pageSize=20" \ -H "Authorization: Bearer {your_access_token}" ``` The response could be `200 OK` with body: ```json { "items": [ { "iccid": "89012345678901234567", "details": { "frequency": 120 } } ], "page": 1, "pageAmount": 1 } ``` Filter by a specific device: ```shell curl -X GET "https://api.1nce.com/management-api/v1/inspect/devices/settings/DEVICE_ADL?iccid=89012345678901234567" \ -H "Authorization: Bearer {your_access_token}" ``` ### Disable Cell tower Plus for Devices Disable Plus location resolution for specific devices. Requires a JSON body with the DELETE request. ```shell curl -X DELETE https://api.1nce.com/management-api/v1/locate/devices/settings \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_access_token}" \ -d '{ "deviceIds": ["89012345678901234567", "89012345678901234568"] }' ``` The response could be `200 OK` with body: ```json { "changedDeviceIds": ["89012345678901234567", "89012345678901234568"] } ``` :::warning The `changedDeviceIds` array lists only devices whose state actually changed from enabled to disabled. ::: --- # Cell Tower Events Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/ ## Cell Tower Events table The Cell Tower Events tab on the Device Locator page lists the cell tower location resolution attempts for the selected device, retained for up to 7 days. Each row shows the event creation time, network access type (for example, LTE-M or NB-IoT), status (resolved by the Basic solver mode or the Plus solver mode), and resolver mode. ## What the Network Event Resolver is The Network Event Resolver re-runs cell tower location resolution with the Plus solver mode for one cell tower event you select on the Cell Tower Events tab. :::info The Network Event Resolver is a free tryout of the Plus solver mode and does not consume any Device Location Credits. The locations it produces are only for testing on demand and are not stored — the resolved data is lost when you close the "Cell tower event details" panel, navigate away, or close the browser tab. ::: Use it to re-resolve a single event that the Basic solver mode resolved imprecisely or failed to resolve, and see whether the higher-accuracy [Plus solver mode](/docs/v2/1nce-os/1nce-os-device-locator/#plus-mode) does better — subject only to the [usage limits](#usage-limits-and-limit-reached-behavior) below. To use the Plus solver mode beyond the tryout, follow the "Upgrade to Plus" path to enable it and its [Device Location Credits](/docs/v2/1nce-os/1nce-os-device-locator/#device-location-credits). To view resolution attempts through the API, use the [Get Device Activity](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity) endpoint. ## Per-event-type guide | Event type | On open | Resolve | |---|---|---| | Succeeded Basic | Red "Basic resolver" marker, detail fields, metadata JSON. | Enabled. | | Failed Basic | No marker plus "Resolve to see the location on the map.", detail fields, metadata JSON. | Enabled. | | Already Plus-resolved | View-only: blue "Plus resolver" marker with accuracy circle and resolved metadata. | Disabled (see [Restrictions](#restrictions)). | | NB-IoT | Detail fields and metadata. | Disabled (see [Restrictions](#restrictions)). | | Read-only role | Map, detail fields, metadata. | Not available. | ## Step-by-step walkthrough 1. Open the Cell Tower Events tab on the Device Locator page for the selected device. 2. Open the "Cell tower event details" panel for the event you want to re-resolve — either hover the row and select the details icon at its end, or select the row. The panel opens docked on the right.
![Cell Tower Events table with the details icon revealed on hover at the end of an event row, the entry point for the Network Event Resolver](/img/1nce-os/plus-resolver-on-demand/events-table-hover.png) Opening an event's details from the Cell Tower Events table.
3. Review the event detail fields: **Device ID (ICCID)**, **Mode**, **Status**, **Access technology**, and **"Cell tower event time"**.
![Cell tower event details panel in its initial state for a Basic event, showing the event detail fields, no resolved map pin, and the event-row metadata JSON](/img/1nce-os/plus-resolver-on-demand/basic-no-resolved-yet.png) The "Cell tower event details" panel before resolving.
4. Select "Resolve" to re-run resolution with the Plus solver mode. The panel shows a loading indicator while it runs, then "Resolve" is disabled — you get a single attempt per event, whether it succeeds or returns no location. 5. On a successful result, the map heading becomes "Map location (Resolved)" and shows the red "Basic resolver" before marker and the blue "Plus resolver" after marker (with an accuracy circle and a legend). If the before and resolved coordinates are identical, only the blue marker is shown.
![Successful on-demand resolution showing the Map location (Resolved) heading, a red Basic resolver before marker, a blue Plus resolver after marker with an accuracy circle, and the legend](/img/1nce-os/plus-resolver-on-demand/basic-resolved-on-demand.png) A successful on-demand Plus solver mode resolution.
6. On a no-location result, a "no location" message is shown, the before marker is retained, and the Status shows "Failed". This result is final and "Resolve" stays disabled.
![Completed on-demand resolution that returned no location, showing the no-location message, the retained before marker, and the Status shown as Failed](/img/1nce-os/plus-resolver-on-demand/on-demand-not-resolved.png) A resolution that returned no location.
7. Use the "View before resolution" / "View after resolution" toggle to switch the metadata between the original and resolved JSON ("Resolution Metadata" becomes "Resolution Metadata (After)", and the after view shows Status "Succeeded" / Mode "Plus"). Select "Copy" to copy the shown JSON.
![Before/after comparison showing the red Basic resolver marker and the blue Plus resolver marker together, the accuracy circle around the blue marker, and a legend listing both resolver rows under the Map location (Resolved) heading](/img/1nce-os/plus-resolver-on-demand/basic-to-plus-comparison.png) Comparing the Basic and Plus locations.
## Usage limits and limit-reached behavior On-demand resolution is capped at 3 resolutions per 60-minute window and 12 per 24-hour window; both apply at once. When you reach either cap, the attempt is blocked and a "Limit reached" dialog appears instead of a result. You cannot resolve again until your usage falls back within both caps.
![Limit reached dialog showing both limit rows, a limiter-specific title and description, a reset line, and the Upgrade to Plus call-to-action](/img/1nce-os/plus-resolver-on-demand/on-demand-rate-limited.png) The "Limit reached" dialog.
The dialog's title and description reflect which limit you reached, and — when a reset time is available — a line tells you when you can resolve again. On the Basic plan, the dialog also offers an "Upgrade to Plus" call-to-action (not shown if the Plus solver mode / ADL is already enabled). ## Restrictions - **NB-IoT is not supported.** For an NB-IoT event, "Resolve" is disabled with the message "Resolution is not available for NB-IoT devices." NB-IoT is the only blocked access type. - **Already resolved by the Plus solver mode.** The panel opens view-only with "Resolve" disabled and the tooltip "This event was already resolved with the Plus resolver." - **Read-only role.** You can open and view the panel, but "Resolve" is not rendered. - **The original event row never changes.** After any attempt, the row keeps its prior Failed or Basic state, whether the attempt succeeded or failed.
![Cell tower event details panel opened view-only for an event already resolved by the Plus solver mode, with the Mode shown as Plus and the disabled Resolve control showing the already-resolved-with-the-Plus-resolver tooltip](/img/1nce-os/plus-resolver-on-demand/plus-already-resolved.png) An event already resolved by the Plus solver mode (view-only).
--- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/device-locator-features-limitations/ ## Features ### Cell Tower Location (Basic and Plus) * The IoT Devices are located by using the cell id of the current tower when creating a new PDP Context or Session used for data transmission. In case the location cannot be determined, the update is skipped and a retry will be done in the next PDP Context/Session. * Using the API, device location and cell tower activity can be queried. The `DeviceId` is equal to the `ICCID`. * The resolved locations of a device can be queried using the [Get Device Positions](/api/1nce-os/get-device-positions/) endpoint. * The cell tower location resolution history (including unresolved records) can be queried using the [Get Device Activity](/api/1nce-os/get-device-celltower-location-resolutions/) endpoint. * Cell tower Plus location mode provides a metadata parameter with accuracy data for resolved locations and tower metadata for unresolved [locations](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/#get-device-activity). * A Basic-plan customer can test Plus (advanced) resolution on demand with the [Network Event Resolver](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-cell-tower-events/), re-running resolution for a single cell-tower event that was previously resolved by the Basic solver mode (a succeeded event) or whose prior resolution failed, directly from the Cell Tower Events tab. ### Geofencing * Using Geofencing functionality it is possible to set virtual boundaries to detect geofence crossing event and receive a notification about it via the [Cloud integrator](/docs/v2/1nce-os/1nce-os-cloud-integrator/). * Users can create up to 10 global geofences across all devices as well as 1 device-specific geofence per-device. * Geofences supports two area types: polygon and circle. * It is possible to define Geofence event types, which control if geofence events will be triggered on device entering or exiting specified area or on both, if not specified then default is to use both. * It is possible to define Geofence event sources, which control if geofence events will be triggered on GPS or Cell Tower location changes or on both, if not specified then default is to use both. * For the circle Geofence which is attached to the device, system will try to retrieve circle center using latest device location in case if user does not pass center during Geofence creation request. ### Per-device Cell tower Plus * Cell tower Plus can be configured on a per-device basis using CUSTOM mode, allowing selective enabling or disabling of Plus location resolution for individual devices via the API or the Plus Resolution tab in the portal. * Each device can have a configurable location resolution frequency between 60 and 1440 minutes. * Managing per-device Plus resolution via the Plus Resolution tab in the portal. * Selecting devices using Single ICCID input, ICCID Range expansion, or CSV file upload. * Configuring and updating frequency for individual or bulk devices. * Deleting per-device configurations individually from the table or in bulk via the Manage SIMs section. * Receiving batch operation results with partial failure feedback including downloadable failed ICCID lists. * See the [Per-device Cell tower Plus guide](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-adl-per-device/) for step-by-step instructions. ## Limitations ### Cell Tower Location (Basic and Plus) * Cell tower **Basic** and **Plus** location modes use different data sources. Currently, Basic mode resolves approximately **30% of locations**, while Plus mode resolves **around 90%**. However, location data can be inaccurate, especially for 3G, 4G, LTE-M, and NB-IoT devices. * If Plus resolver mode is enabled, then [Device Location credits](/docs/v2/1nce-os/1nce-os-device-locator/#device-location-credits) will be consumed. * NB-IoT locations are not being resolved with Plus resolver. * After activating the cell tower location setting it can take a few minutes before the first location will be available. * Cell tower location data is resolved no more frequently than once an hour. * For customers in Brazil and China, current service limitations may impact our ability to accurately determine device cell-tower location and maintain a complete location history. This may result in less accurate or incomplete location information. * To view the location history of specific device on the map you have to switch to the Device Inspector in the 1NCE OS Portal. * The Cell tower events tab displays data for a single device selected in the filter. * Network Event Resolver on-demand testing is rate-limited to at most 3 resolutions per hour and at most 12 within any 24-hour window; both limits apply. When either limit is reached, a "Limit reached" dialog blocks further attempts until usage falls back within the limits. * The Network Event Resolver on-demand result is transient and provided only for testing the Plus solver mode. It is not stored or persisted, and is lost when you close the "Cell tower event details" panel, navigate away, or close the browser tab. ### Geofencing * Polygon geofences support a maximum of 50 coordinate points (including the closing point). * Circle geofence radius must be between 50 m (minimum) and 30,000 m (maximum). * User can update only Geofence name, event types and event sources, coordinates and Geofence type cannot be changed to prevent possible confusion with the previous exit or enter events. * Geofence creation and enter/exit events require active [Geofence credits](/docs/v2/1nce-os/1nce-os-device-locator/#geofence-credits). ### Per-device Cell tower Plus * Per-device Cell tower Plus requires the customer to have purchased Device Location credits. * Per-device Cell tower Plus requires the ADVANCED_CELL_TOWER_LOCATION setting to be enabled with mode set to CUSTOM. * A maximum of 100 device IDs can be enabled or disabled in a single batch operation (API request or portal submission). * Switching from CUSTOM to DEFAULT mode is not available through the API or the portal. * New SIMs activated in CUSTOM mode default to basic resolution until explicitly enabled via the API or the portal. * Per-device Cell tower Plus consumes Device Location credits, when credits are exhausted, resolutions stop but per-device configurations are preserved. * CSV file upload in the portal Plus Resolution tab is limited to 200 KB. --- # Geofence creation guide Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/ ## Prerequisites Before creating geofences, ensure that [Geofence Credits](/docs/v2/1nce-os/1nce-os-device-locator/#geofence-credits) are available in your account. Without active credits, geofence creation is not possible. ## Creating a Geofence To create a new geofence, click the **+ Create Geofence** button on the Device Locator page.
![Create Geofence button](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/create-geofence-button.png) *Create Geofence button*
### Scope Select the scope for the new geofence — **Global** or **Device Specific**. * **Global** geofences apply to all devices in your account. You can create up to 10 global geofences. * **Device Specific** geofences are tied to a single device (identified by ICCID). You can create 1 device-specific geofence per device.
![Geofence scope selection](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofence-scope.png) *Geofence scope selection*
### Name Enter a name for the geofence. :::info Naming convention for device-specific geofences For device-specific geofences, you can later filter geofences either by entering the full ICCID or by searching multiple geofences by name prefix. Choosing a consistent naming convention (e.g., a shared prefix like `warehouse-` or `fleet-`) makes it easier to find and manage groups of device-specific geofences. ::: ### Type Select the geofence shape — **Polygon** or **Circle**. * **Polygon** — draw the geofence boundary directly on the map by placing up to 50 coordinate points.
![Drawing a polygon geofence on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofene-polygon.png) *Polygon geofence*
* **Circle** — draw a circle around a selected center point on the map. The radius must be between 50 m and 30,000 m.
![Drawing a circle geofence on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/new-geofene-circle.png) *Circle geofence*
### Event Types Choose which crossing events should trigger a [geofence event](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/#geofence): * **Enter** — triggered when a device enters the geofence boundary * **Exit** — triggered when a device exits the geofence boundary * **Enter & Exit** — triggered on both entry and exit ### Event Sources Select the location data source used to evaluate geofence crossings: * **[Cell Tower](/docs/v2/1nce-os/1nce-os-device-locator/#cell-tower-location)** — uses cell tower-based location data * **[GPS](/docs/v2/1nce-os/1nce-os-device-locator/#gps-location)** — uses GPS coordinates reported by the device (via [Energy Saver](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/) or [LwM2M](/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/)) * **Cell Tower & GPS** — evaluates against both sources ### ICCID (Device Specific only) Enter the ICCID of the device. The system can automatically determine the latest device location (if available). **Device location is available:** When creating a device-specific geofence with the Circle type, the system retrieves the latest known device location. To use this location as the center of the circle, click the location icon next to the filled ICCID field.
![Device-specific geofence with known location](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/device-specific-location-known.png) *Device location available*
**Device location is not available:** If the device does not have a known location, the system cannot automatically determine its position. You will need to draw the geofence boundary manually on the map.
![Device-specific geofence with unknown location](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/device-specific-location-unknown.png) *Device location not available*
## Viewing Geofences Besides viewing geofences in the portal, you can also retrieve the full list programmatically via the [Get all geofences](/api/1nce-os/get-all-geofences/) API endpoint. ### Global Geofences When the global geofences view is selected, all global geofences are loaded and shown in the dropdown list. All global geofences are also placed on the map.
![Viewing global geofences on the map](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-global-geofences.png) *Global geofences view*
### Device Specific Geofences When looking for device-specific geofences, you can either enter the full ICCID or use a name prefix to filter results (up to 10 geofences will be shown). **By full ICCID:**
![Viewing device geofence by ICCID](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-device-geofence-by-iccid.png) *Filter by full ICCID*
**By name prefix:**
![Viewing device geofences by name prefix](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-device-geofence-by-prefix.png) *Filter by name prefix*
## Editing and Deleting Geofences By clicking on a geofence, you can view its details and choose to **Edit** or **Delete** it.
![Geofence details with Edit and Delete options](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/view-geofence-details.png) *Geofence details*
When editing a geofence, only the following fields can be changed: * **Name** * **Event Types** * **Event Sources** Coordinates and geofence type cannot be modified. To change the shape or location, delete the existing geofence and create a new one.
![Editing a geofence](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/edit-geofence.png) *Edit geofence*
## Quick Test: End-to-End Validation Ensure you have active [Geofence Credits](/docs/v2/1nce-os/1nce-os-device-locator/#geofence-credits) before proceeding. Follow these steps to quickly validate that your geofence setup is working correctly. **1. Create a Cloud Integration** Set up a [Webhook Cloud Integration](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-webhook-configuration/#webhook-creation) and select **Geofence** as the Event Type. A temporary webhook (e.g., using [webhook.site](https://webhook.site)) is sufficient for testing purposes. **2. Simulate a GPS location for your device** Use the Energy Saver [template example](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/#template-example) to send a GPS location from your device. This establishes the initial device position. **3. Create a device-specific geofence using the device location** Create a device-specific circle geofence as described in the [ICCID section](#iccid-device-specific-only). The system will use the location reported in step 2 as the center of the geofence. **4. Simulate new GPS locations that enter and exit the geofence** Using the same Energy Saver template example, send GPS coordinates that are inside and then outside the geofence boundary. This triggers Enter and Exit events. **5. Validate geofence events in the Webhook** Check your webhook endpoint for incoming geofence events. You should see **ENTER** and/or **EXIT** events depending on the simulated locations and your geofence event type configuration. ## Retrieving Geofence events After geofence is created, [Cloud integrator](/docs/v2/1nce-os/1nce-os-cloud-integrator/) will create **ENTER** and **EXIT** events on every geofence border crossing by device, depending on the configuration of geofence `eventTypes`, `eventSources` and also device location update frequency.
![Geofence EXIT event from GPS source](/img/1nce-os/1nce-os-device-locator/device-locator-geofencing-guide/Geofence-event-in-aws-intergration.png) *Geofence EXIT event from GPS source in AWS Cloud Integration*
Please see [Cloud integrator output format](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-output-format/) for details of geofence events. --- # Energy Saver Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/ ![](/img/1nce-os/1nce-os-energy-saver/energy-saver.png) With the energy saver, 1NCE offers a simple way to decode freeform third-party binary payloads. With the help of BCL, JSON objects are created. This chapter will guide through the setup and usage process with full examples and code snippets. --- # Binary Conversion Language Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language/ The goal of the Binary Conversion Language (BCL) is to provide an easy way of defining a schema for decoding freeform third-party binary payloads. A set of mappings in BCL specific to a device type is called a conversion. Conversions are encoded as JSON objects. More details on the general conversion language available at [https://docs.allthingstalk.com/dl/AllThingsTalk\_Binary\_Conversion\_Language\_1\_0\_0.pdf](https://docs.allthingstalk.com/dl/AllThingsTalk_Binary_Conversion_Language_1_0_0.pdf) ## Structure of a conversion ```json Example: Home alarm system { "name": "alarm", "comment": "Home alarm system", "version": "1.0.0", "sense": [ { "asset": "motion", "value": { "byte": 0, "bytelength": 1, "type": "boolean" } } ] } ``` In this example, we declare a data conversion used with a home alarm system device. When the device senses motion it sends one byte to [UDP endpoint](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-udp/). This simple template converts that one byte sent by the device into a JSON object with a boolean field called `motion`. When the device with enabled binary translation, sends `0x01` the byte gets translated into `true` resulting in the following object: ```json { "motion": true } ``` ## Top-level fields A conversion MUST have a list field named `sense`, which contains statements that need to be evaluated during `sensing` - when de-serializing binary payloads into JSON objects. A conversion MAY have a string field named `comment`, provided for a human-readable description of the conversion. ## Statements Statements are JSON objects that describe a single operation that needs to be performed in a conversion. A statement MUST be either a mapping statement, a control statement, or a comment statement. Statements appear in statement blocks. ## Statement blocks Statement blocks are JSON lists whose elements are statements or statement blocks that need to be performed in order to complete the conversion. A statement block MAY contain no elements. Making a statement block empty is the same as omitting it all together - no statements get executed. This can be useful in code generation. There are two types of statement blocks: `sense` and `do`. `sense` statement blocks are executed when sensing (receiving data), and they are present in the home alarm example. `do` is used wherever embedding a statement block - usually within control structures - is needed. ## Sense block Sense block MAY contain mapping statements and control statements. Mapping statements in sense block MUST contain a string field `asset`, whose value is a string that uses JSON dot-notation to identify the path to the field in the resulting object. Mapping statements in sense block MUST contain a field `value`, whose value is a selector that identifies the data that will be stored as the new value of the asset. Mapping statements in sense block MAY have a string field named `comment`, provided for human-readable description of the given mapping. ## Mapping statements Mapping statements are used for de-serializing values and metadata from specific parts of binary payloads, special values, variables, and constants into fields in the resulting JSON. The statement contains two fields: `asset` - Path to resulting field using JSON dot notation\ `value` - Constant or payload selector Examples: **Inject a string field using the constant selector.** ```json Example - sense { "sense": [ { "asset": "sensor", "value": "motion" } ] } ``` Result: ```json Example - sense result { "sensor": "motion" } ``` **Convert 4 bytes into a 32-bit floating-point number using payload selector. Longitude from GPS beacon** ```json sense longitude example { "sense": [ { "asset": "longitude", "value": { "byte": 0, "bytelength": 4, "byteorder": "big", "type": "float" } } ] } ``` Data: - `42 4b bc f9` Result: ```json sense longitude example result { "longitude": 50.934544 } ``` ## Control statements Control statements MUST have a JSON object field named `switch` that specifies the payload selector that's going to be evaluated, and its value tested in cases. Control statements MUST have a JSON array field named `on` that contains a list of cases that switch value will be tested on, optionally including the default case. Control statements are used for executing control logic that MAY lead to executing more statements. The switch is the only available control statement in this version of BCL. Control statement MAY have a string field named `comment`, provided for human-readable description of the conversion. Control statement on list MAY contain zero or more case statements. The control statement on the list MAY contain a comment statement. ## Case statements The case statement MAY have a JSON object field named `case`, whose value is a selector whose value is tested with the switch selectors value in the outer switch control statement. If it is equal, `do` statement block is executed. The switch logic supports optional `default` case. If field `case` is not present in the case statement, a field `default` MUST be present with value `true` marking this object a default case of the switch. Case statement MUST have a JSON list field named `do`, whose value is a statement block that is executed if case and switch match. If no `case` statements match the payload, and the `default` case is defined, the default case is executed instead. If `default` case is not present and no `case` statements match, nothing is executed. Example: In this example, payload first byte is an 8-bit integer that defines message type. Message type 0 is positional data about the vehicle and message type 1 is maintenance data. Message type 0 has the following structure: ```text Message Structure Full Example +-------------------+------------------+-------------+ | 4 bytes | 4 bytes | 2 bytes | +-------------------+------------------+-------------+ | Longitude (float) | Latitude (float) | Speed (int) | +-------------------+------------------+-------------+ ``` Let's initialize the switch statement and create the condition for message type `0` ```json Full Example { "sense": [ { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "comment": "Positional data", "do": [ { "asset": "gps.lat", "value": { "byte": 1, "bytelength": 4, "byteorder": "big", "type": "float" } }, { "asset": "gps.lon", "value": { "byte": 5, "bytelength": 4, "byteorder": "big", "type": "float" } }, { "asset": "speed", "value": { "byte": 9, "bytelength": 2, "byteorder": "big", "type": "int" } } ] }, { "default": true, "do": [ { "asset": "error", "value": "unknown payload" } ] } ] } ] } ``` Device sends the following data `00 42 4b bc f9 40 de 98 1c 00 78` First byte `00` determines that this message contains positional data. The message will result in the following object: ```json Full Example Result { "gps": { "lat": 50.934544, "lon": 6.956068 }, "speed": 120 } ``` If device sends the following data `01 ff ff ff`, the first byte `01` does not match the defined case statement, meaning the default statement is executed: ```json Full Example Result { "error": "unknown payload" } ``` ## Selectors Selectors are JSON values. They are used to “select” data from a given location type or “select” data used in a control statement. Selectors MAY have a string field named `comment`, provided for human-readable description of the conversion. ## Constant selector The constant selector is a string. Example: ```text "foo" ``` ## Payload selector A payload selector is a JSON object. Payload selector MUST have an integer field named `byte` AND/OR an integer field named `endbyte`. The value of `byte` field represents the starting byte from which the chunk is going to be selected (counting from the beginning of the payload). The value of `endbyte` represents a byte counting from the end of the payload and is described as a value that is less or equal to zero. If both `byte` and `endbyte` are present in the payload selector, they are representing a range selector "from `byte` to `endbyte`". Payload selector MAY have an integer field named `bytelength`, whose value represents the length of the chunk in bytes, starting from and including the byte indexed by `byte` field. It defaults to 1. The field `bytelength` MUST NOT be present if the payload selector contains both `byte` and `endbyte`. Payload selector MAY have a string field named `byteorder`, whose value represents the byte order of the chunk of bytes. Values for this field can be `big` (Big Endian) or `little` (Little Endian). This value defaults to the `big`. Payload selector MUST have an integer field named `type`, which defined the data type to which bytes should be converted. Examples: Select 16-bit integer with little endian: ```json 16-bit integer select { "byte": 1, "bytelength": 2, "type": "int", "byteorder": "little" } ``` Select whole payload as a hex string: ```json whole payload section { "byte": 0, "endbyte": 0, "type": "hex" } ``` Select the last 4 bytes of the payload as a 32-bit unsigned integer (Big Endian by default): ```json last 4 bytes as 32-bit uint { "endbyte": -4, "bytelength": 4, "type": "uint" } ``` Supported data types **Numeric** `bytelength` is required. A fix was provided to use the default value of 1 byte if `bytelength` field is not provided inside selectors. `int` - signed integer. Can have `bytelength` 1, 2, 4, 8 which are 8-bit to 64-bit integers respectively. Defaults to 1\ `uint` - unsigned integer. Same constraints as `int`. ```text int and unit value ranges int and uint value ranges uint8 : 0 to 255 uint16 : 0 to 65535 uint32 : 0 to 4294967295 uint64 : 0 to 18446744073709551615 int8 : -128 to 127 int16 : -32768 to 32767 int32 : -2147483648 to 2147483647 int64 : -9223372036854775808 to 9223372036854775807 ``` `float` - floating-point number. Can have `bytelength` 4 and 8 which are 32-bit floating-point number and 64-bit double precision floating-point number. **Boolean** `boolean` - boolean. 0x00 will be treated as false. **String** `string` - UTF-8 encoded string. **Hex** `hex` - output as hex string. ## Nested structure Dot notation can be used to create JSON with a nested structure. ```json Example - nested { "sense": [ { "asset": "simple_key", "value": "value1" }, { "asset": "level1.level2.level3.level4", "value": "value2" } ] } ``` ```json Result - nested { "message": { "level1": { "level2": { "level3": { "level4": "value2" } } }, "simple_key": "value1" } } ``` ## Full Example Let's now fully expand all the pieces that we've talked about in this document. ```json Full Example { "sense": [ { "asset": "message_code", "value": { "byte": 0, "bytelength": 1, "type": "uint" } }, { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "comment": "Positional data", "do": [ { "asset": "data_type", "value": "Position" }, { "asset": "gps.lat", "value": { "byte": 1, "bytelength": 4, "type": "float" } }, { "asset": "gps.lon", "value": { "byte": 4, "bytelength": 4, "type": "float" } }, { "asset": "speed", "value": { "byte": 8, "bytelength": 2, "type": "int" } } ] }, { "case": 1, "comment": "Maintenance data", "do": [ { "asset": "data_type", "value": "Maintenance" }, { "asset": "on", "value": { "byte": 1, "type": "boolean" } }, { "asset": "fuel", "value": { "byte": 2, "bytelength": 4, "type": "uint" } }, { "asset": "driver", "value": { "byte": 6, "bytelength": 4, "type": "string" } }, { "asset": "driver_hex", "value": { "byte": 6, "bytelength": 4, "type": "hex" } } ] }, { "default": true, "do": [ { "asset": "data_type", "value": "Unsupported type" } ] } ] }, { "asset": "full_payload", "value": { "byte": 0, "endbyte": 0, "type": "hex" } } ] } ``` As before, this template parses two types of messages indicated by the first byte. In the beginning, though there is a new mapping statement that adds message type to the resulting JSON. In the switch block, a new statement is added to parse maintenance data. Data: `01 01 00 00 05 8c 6f 6c 65 67` The first byte is always mapped to `message_code`. Field `data_type` is a constant selector that will be evaluated to `Maintenance`. `0x01` -> 1 The message therefore should be parsed as maintenance data. We have already tried parsing Positional data, the example can be found above. Let's explore how the `switch` statement will work in this case. The byte at position 1 is parsed as a boolean and mapped to on, which determines if the vehicle is powered on. `0x01` -> true Next, fuel level is parsed from four bytes starting at position 2 and mapped to field `fuel`. Fuel will be parsed as `unit`, which is an unsigned integer because fuel can't drop below 0. Since 4 bytes is selected, the number will be parsed into 32-bit uint. `0x0000058c` -> 1420 Driver name is then parsed as a string. Name is parsed from 4 bytes starting from position 6. `0x6f6c6567` -> "oleg" Driver name is also outputted as hex string and mapped to field `driver_hex`. `0x6f6c6567` -> `6f6c6567` We also are adding the whole original payload to the output as hex in the field called `full_payload`. We are selecting the whole payload by defining the start of the selector as `byte: 0` and the end as `endbyte: 0`. We get the following result for our Translated Binary Payload. ```json Full Example - Result { "message_code": 1, "data_type": "Maintenance", "on": true, "fuel": 1420, "driver": "oleg", "driver_hex": "6f6c6567", "full_payload": "01010000058c6f6c6567" } ``` --- # Device Locator Integration Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-device-locator-integration/ It is possible for the device to send binary messages, use the Energy Saver to decode these messages, and send valid GPS data to the [device locator](/docs/v2/1nce-os/1nce-os-device-locator/) service.\ To accomplish this integration, it is required to create an Energy Saver template and include the `custom_type` in the JSON template with the names `location_lat` and `location_long` to mark the latitude and longitude values respectively.\ GPS data can be: * Visualized in the 1NCE OS portal [device inspector](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/) & [device locator](/docs/v2/1nce-os/1nce-os-device-locator/) tabs. * Used via [API](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/). * Forwarded to [cloud integrator](/docs/v2/1nce-os/1nce-os-cloud-integrator/). ### Template example **Energy Saver** template to decode longitude in the first 8 bytes and latitude in the subsequent 8 bytes of the message. ```json { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` ### Code snippet Example of generating a GPS payload: * Sends to the 1NCE OS UDP endpoint as a binary payload. * Prints the payload in Base64 format for testing with the Energy Saver template on the 1NCE OS portal or via the [API](/api/1nce-os/test-template/). ```javascript const dgram = require('dgram'); // Server and message configuration const serverPort = 4445; const serverAddress = 'udp.os.1nce.com'; const latitude = 56.946285; const longitude = 24.105078; function encodeLocation(latitude, longitude) { const latBuff = processFloat(latitude); const longBuff = processFloat(longitude); return Buffer.concat([longBuff, latBuff]); } function processFloat(val) { // Assign the same byte length as defined in the template let buf = Buffer.alloc(8); buf.writeDoubleLE(val); return buf; } const message = encodeLocation(latitude, longitude); const client = dgram.createSocket('udp4'); client.send(message, serverPort, serverAddress, (err) => { if (err) { console.error('Error sending message:', err); } else { console.log('UDP message sent successfully as binary payload!'); } client.close(); }); console.log("Payload in base64 format for energy saver template testing in 1NCE OS Portal or via API:", message.toString('base64')); ``` --- # Energy Saving Calculation Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation/ By using the 1NCE Energy Saver with a translation template, the devices can save energy. How much energy is saved, depends on the optimized payload compared to the original full JSON. Below is a description of how the saved energy for 1NCE customers can be calculated based on 1NCE research. The research focusses on the impact of the energy saver on correlation of the translation compared to the usage of the battery. The tests were executed sending CoAP-Messages with translation capabilities in various degrees. # Test-Setup Tools used: * Testing device: NRF Development kit (Nordic nRF9160-DK) * Device power measurement: Qoitech Otii arc Testing rules: * Energy saver using CoAPs (NB-IoT – stable connection) * Incremental payload (50B – 2KB) * Duration of Test: 3 hours * Frequency of messages: 4 messages/minute # Result Measurements: | Payload Size (Bytes) | 1st Hour | 2nd Hour | 3rd Hour | Average consumption (mWh) | | :------------------- | :------- | :------- | :------- | :------------------------ | | **50** | 94.5 | 95 | 92.3 | 93.1 | | **250** | 101 | 98 | 95.1 | 98.0 | | **500** | 101 | 101 | 98.1 | 100.0 | | **1000** | 107 | 106 | 111 | 108.0 | | **1500** | 112 | 113 | 117 | 114.0 | | **2000** | 121 | 118 | 119 | 119.3 | ![Payload vs. Consumption](/img/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation/energy-used-graph.png) The energy consumption of the IoT device can be calculated by: **E = 0.013 x + 94.084** Where **E** is the energy consumption and **x** ist the Payload in Bytes. For every Byte less in communication you save an average of 0.013 mWh. `
`Ereduced = E(xoriginal) - E(xoptimized)`
`
  • xoptimized is the payload from the device that is using a translation template
  • xoriginal is the value that will result after the optimized payload is translated (full JSON string)
The average amount of saved energy is the difference between the energy consumption of the full JSON and the energy consumption of the optimized payload. Please be aware that the average amount of saved energy is an estimated value and not an actual measurement. In the tests, the payload was varied in all experiments to avoid caching by network (or software). # Example Payload ```Text base64 00 1A 00 37 00 ``` Output ```Text Optimized JSON { "Temperature": 26, "Humidity": 55, "Switch": FALSE } ```
  • Payload = 10 Bytes (xoptimized)
  • Output = 47 Bytes (xoriginal)
  • Amount of Saved Bytes = 37 Bytes
  • Energy Saved (Ereduced) = 0.481 mWh
Compared to the energy of the original payload we save 0.51% of energy in this example. General rule of thumb, small payloads only result in a small energy saving. The larger the payload and the greater the optimization, the more energy is saved. --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-features-limitations/ ## Features The 1NCE Energy Saver offers binary conversion inspired on the AllThings Talk Binary Conversion Language (ABCL) but we don't support all the all features. More details on the general conversion language available at [Binary Conversion Language](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language/) The binary conversion allows customers to simply format binary payloads and build also more complex logic into the conversion templates. Templates are provided via the 1NCE Energy Saver and applied to the desired Devices.\ Let's take the following example for a simple IoT device with 2 sensors one input. A UDP payload would look like this: **00 1A 00 37 00** As this is not readable let's apply the following conversion template to the message: ```json { "sense": [ { "asset": "Temperature", "value": { "byte": 0, "bytelength": 2, "type": "int", "signed": true } }, { "asset": "Humidity", "value": { "byte": 2, "bytelength": 2, "type": "int" } }, { "asset": "Switch", "value": { "byte": 4, "type": "boolean" } } ] } ``` This will result in a nicely formatted JSON-message that is also human-readable: ```json { "Temperature": 26, "Humidity": 55, "Switch": false } ``` Desired template can be edited and tested using [Template Tester](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/) ## Limitations * Only values between -9999999999999999 and 9999999999999999 are guaranteed to have the correct precision. Values smaller than -9999999999999999 and larger than 9999999999999999 could be affected by rounding precision. * API requests have a maximum request body size limit of 64kb, which includes all the information sent in the request body. This limitation can potentially affect requests to [create](/api/1nce-os/create-optimizer-template/) and [patch](/api/1nce-os/update-optimizer-template/) template endpoints, since the size of the template and other information sent in the request body cannot exceed 64kb. * Only 1 **Energy Saver** template is allowed per protocol (UDP and CoAP). --- # Template tester Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/ # Edit and Test To help with creating optimized translation templates for your needs to meet best energy and data saving expectation 1NCE OS provides: * an interface to **Edit and Test** the desired template. * [API](/api/1nce-os/test-template/) endpoint to test the template. Template tester is a tool that processes the given **Binary** payload in Base64 string format using the template in template editor and returns the JSON output, translating the Base64 binary payload into readable format. Note that Base64 string binary representation is used only for testing purpose, the actual translation of message is done from **Binary** into **JSON**.\ Also, until changes are saved and template is in active state the template changes does not affect the flow of CoAP or UDP messages.
![Edit and Test template interface](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/template-edit-and-test.png)
# Example templates There are 3 example templates provided to start with or just create your own template from scratch. To try example templates just expand the list of example templates, select any desired template and press **Use this template** button. It will insert example template into template editor, provide example payload into input field. Now you are ready to do the template testing.
![Example templates](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/example-templates.png)
### Location template ``` { "sense": [ { "asset": "longitude", "custom_type": "location_long", "value": { "byte": 0, "bytelength": 8, "type": "float", "byteorder": "little" } }, { "asset": "latitude", "custom_type": "location_lat", "value": { "byte": 8, "bytelength": 8, "type": "float", "byteorder": "little" } } ] } ``` If custom types location\_long and location\_lat are available the position will be forwarded to the [Location Service](/docs/v2/1nce-os/1nce-os-device-locator/). Longitude and latitude both have to be float64. ### Deep JSON ``` { "sense": [ { "asset": "car.running", "value": { "byte": 0, "type": "boolean" } }, { "asset": "car.fuel", "value": { "byte": 1, "bytelength": 4, "type": "uint" } }, { "asset": "car.driver", "value": { "byte": 5, "bytelength": 4, "type": "string" } } ] } ``` By including dots in the asset name, deep JSON objects can be created. ### Switch statement ``` { "sense": [ { "switch": { "byte": 0, "bytelength": 1, "type": "int" }, "on": [ { "case": 0, "do": [ { "asset": "data_type", "value": "environment" }, { "asset": "temperature", "value": { "byte": 1, "bytelength": 4, "type": "float" } } ] }, { "case": 1, "do": [ { "asset": "data_type", "value": "device" }, { "asset": "on", "value": { "byte": 1, "type": "boolean" } } ] } ] } ] } ``` The [statements](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-binary-conversion-language/#case-statements) inside do will be executed if the value of case (within the same object as do) and the switch match. # Test results ## Test failed When template is incorrect and template tester can't process the payload, the error message appears under the edit field describing the error:
![Template expects 17 bytes while only 16 bytes are provided](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/invalid-template.png)
## Test succeeded Output field below template editor provides the translated template value in readable format. As an additional template performance metrics the **Reduced Bytes** is provided that represents payload size difference between OUTPUT and INPUT of template as well as **Energy Saved** value that is calculated according to our research described in [Energy Saving Calculation](/docs/v2/1nce-os/1nce-os-energy-saver/energy-saver-energy-saved-calculation/) article. Reduced bytes and Energy saved metrics represents savings on every message that is sent by device
![Test succeeded](/img/1nce-os/1nce-os-energy-saver/energy-saver-template-tester/template-metrics.png)
--- # LwM2M Service Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-overview.png)
Lightweight M2M (LwM2M) is a protocol standard specified by the Open Mobile Alliance (OMA LwM2M) with the goal to offer a fast client-server specification for Machine-to-Machine (M2M) and Internet of Things (IoT) communication and management services. LwM2M defines an application layer protocol between any arbitrary client (e.g., IoT device with 1NCE OS) and a LwM2M server (e.g., 1NCE OS LwM2M Integration). Exchanging data by using the light and secure LwM2M communication interface along with the efficient data model, enables device management and service enablement for constrained IoT and M2M devices. The unified LwM2M protocol standard makes it possible to bring a wide range of supported LwM2M devices from different vendors and application categories together and integrate these connected devices into one common communication and management interface. The LwM2M specification provides general APIs for device configuration, connectivity monitoring/statistics, security and firmware update, server provisioning and is constantly extended. The widely used Constrained Application Protocol (CoAP) provides in-built binding for LwM2M, thus making the LwM2M protocol particularly appealing for the Internet of Things (IoT) using mobile connectivity. The standard is targeted, in particular, at constrained devices, e.g., devices with low-power microcontrollers and small amounts of Flash and RAM over networks requiring efficient bandwidth usage. At the same time, LwM2M can also be utilized with more powerful embedded devices that benefit from efficient communication. The first release of LwM2M 1.0 dates back to February 2017. Since then, regular feature and maintenance updates have been released. Currently LwM2M 1.2 represents the current standard. To get updates on the latest developments, please visit the OMA LwM2M website. A large consortium of well-known IoT hardware and software manufacturers have committed resources to enhance and further develop the LwM2M standard in their products. To this day, many LwM2M application notes from mobile network modem and connectivity device manufactures have been released. The addition of LwM2M to the portfolio of the 1NCE Services allows 1NCE customers to directly use LwM2M as part of their IoT device integration and management. The following chapters outline the features and limitations of the 1NCE LwM2M service, provide a basic introduction into LwM2M and offer a range of use case examples to get you successfully started using 1NCE Connect in combination with the 1NCE LwM2M Service. --- # Bootstrapping Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping/ To use the 1NCE LwM2M Service, every time a client IoT device with a 1NCE SIM wants to connect or reattach, the bootstrap server needs to be contacted at first. A direct connection to the LwM2M server without prior communication towards the bootstrap service is not possible. The task at hand for the bootstrap server is to accept the initial connection, handle the authorization of the SIM device using the SIM-as-an-Identity service and provide LwM2M server connectivity instructions with one-time specific security credentials. There are two possible methods to bootstrap a device. The bootstrapping can be performed either by encrypted DTLS communication (using PSK) or by using Plain COAP. DTLS is using pre-shared key (PSK) provided by client device and identity of device (deviceId-iccid). If device is bootstrapping to secure server, the LWM2M server priority is changed to also secure server to be first. The PSK can be set: * using 1NCE OS API endpoint described in [API Explorer](/api/1nce-os/create-pre-shared-device-key/) * in 1NCE OS portal Device Integrator when [testing lwm2m endpoint](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/#testing-the-endpoint) Using [leshan client](https://github.com/eclipse/leshan#test-leshan-demos-locally) there is 2 examples to bootstrap: 1. **DTLS** `java -jar .\leshan-client.jar -b -u lwm2m.os.1nce.com:5684 -p -i ` 2. **PLAIN** `java -jar .\leshan-client.jar -b -u lwm2m.os.1nce.com:5683` The following figure illustrates this process in detail.
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping/lwm2m-bootstrapping.png)
### The shown steps are the following (plain connection): 1. The LwM2M client calls the bootstrap server at `lwm2m.os.1nce.com:5683` using plain CoAP. 2. The bootstrap server responds with a data message containing all the necessary information for the client to connect to the actual LwM2M server. **LwM2M Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/0/0 | LWM2M Server URI | String | Example: `coap://1.2.3.4:5683` | | 0/0/1 | Bootstrap-Server | Boolean | false | | 0/0/2 | Security Mode | Integer | 3 (NoSec) | | 0/0/10 | Server Id | Integer | 1111 | | 1/0/0 | Short Server ID | Integer | 1111 | | 1/0/1 | Lifetime (s) | Integer | 86400 | | 1/0/2 | Default Minimum Period (s) | Integer | 1 | **Bootstrap Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/1/0 | Bootstrap Server URI | String | Example: `coap://lwm2m.os.1nce.com:5683` | | 0/1/1 | Bootstrap-Server | Boolean | yes | | 0/1/2 | Security Mode | Integer | 3 (NoSec) | | 0/1/10 | Server Id | Integer | 2222 | 3. The LwM2M client device uses this information to trigger the registration on the LwM2M server using CoAP. ### The shown steps are the following (with DTLS): 1. The LwM2M client calls the bootstrap server at lwm2m.os.1nce.com:5684 using CoAPs. 2. The bootstrap server responds with a data message containing all the necessary information for the client to connect to the actual LwM2M server. **LwM2M DTLS Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/0/0 | LWM2M Server URI | String | Example: `coaps://1.2.3.4:5684` | | 0/0/1 | Bootstrap-Server | Boolean | false | | 0/0/2 | Security Mode | Integer | 0 (Pre-Shared Key) | | 0/0/3 | Identity | Opaque | *Identity as binary data* | | 0/0/5 | Secret Key | Opaque | *Private key for LwM2M Server as binary data* | | 0/0/10 | Server Id | Integer | 1111 | | 1/0/0 | Short Server ID | Integer | 1111 | | 1/0/1 | Lifetime (s) | Integer | 86400 | | 1/0/2 | Default Minimum Period (s) | Integer | 1 | **Bootstrap DTLS Server** | Resource | Description | Type | Value | | --- | --- | --- | --- | | 0/1/0 | Bootstrap Server URI | String | Example: `coaps://lwm2m.os.1nce.com:5684` | | 0/1/1 | Bootstrap-Server | Boolean | yes | | 0/1/2 | Security Mode | Integer | 0 (Pre-Shared Key) | | 0/1/3 | Identity | Opaque | *Identity as binary data* | | 0/1/5 | Secret Key | Opaque | *Private key for LwM2M Bootstrap Server as binary data* | | 0/1/10 | Server Id | Integer | 2222 | 3. The LwM2M client device uses this information to trigger the registration on the LwM2M server using CoAPs. The DTLS Pre Shared Key (PSK) that is provided by the bootstrap server and used for the registration is regenerated on every bootstrap request. --- # LwM2M Service Client Example Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-client-examples/ > ❗️ 1NCE SIM Connectivity > > For running the examples, a device/system with a 1NCE SIM that has an active data session connection needs to be used to send the request towards the 1NCE Services. The data traffic needs to be issued via the mobile network connection. Two commonly used LwM2M Clients are Eclipse Leshan (JAVA) and Eclipse Wakaama (C). This example section covers a basic guide for both LwM2M implementations on how to use them with the 1NCE LwM2M Service. # Eclipse Leshan Please review the Leshan GitHub page for reference. The Leshan Client Demo can be built as a Java Maven project. The JAVA client can be started with the following settings: ```shell java -jar ./target/leshan-client-demo-2.0.0-SNAPSHOT-jar-with-dependencies.jar -b -u lwm2m.os.1nce.com:5683 ``` To emulate a Send Operation, enter the `send 6` operation. To change the frequency of registration updates, in the Leshan client `DefaultRegistrationEngineFactory` should be updated with a specific communication period (example, make registration update trigger every 30 seconds): ```java LeshanClientBuilder builder = new LeshanClientBuilder(cli.main.endpoint); ... // Configure Registration Engine DefaultRegistrationEngineFactory engineFactory = new DefaultRegistrationEngineFactory(); ... engineFactory.setCommunicationPeriod(30000); ... builder.setRegistrationEngineFactory(engineFactory); ``` *** # Eclipse Wakaama Please review the Wakaama GitHub page for reference.\ Wakaama has a Client Example GitHub which should be built as instructed and started with: ```shell ./lwm2mclient -b -h lwm2m.os.1nce.com -p 5683 -4 ``` --- # Data Handling Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/
![](/img/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/lwm2m-flow.png)
In general, there are two options how data from a LwM2M client device can be transmitted towards the LwM2M Server. The send operation represents the push-orientated communication, whereas passive reporting reflects the pull-based data exchange. In the following section, both these data exchange methods are outlined. Further an outline to viewing and accessing the LwM2M data and further references are provided. *** # Send Operation An active LwM2M client that is registered on the LwM2M server can send data by executing a simple send operation. This send is used by the LwM2M client to "push" data to the LwM2M server without an explicit request by this server. This operation is used by the client to report values for resources and resource instances of known and existing LwM2M object instance(s) (OMA LwM2M Registry.) to the LwM2M Server. *** # Passive Reporting Passive reporting provides a pull-based data collection method, where data is requested from a LwM2M device. By enabling passive reports, the 1NCE LwM2M server tries to read all known readable objects of the LwM2M client. This read is timed based on the registration and registration update events. The read out data is also provided via the IoT Integrator. An object is considered readable if at least one of its resources is readable. LwM2M object IDs 1, 2, and 3 are excluded from this read operation. ## Enable Reporting To use passive reporting with the 1NCE LwM2M Service, the `LWM2M_PASSIVE_REPORTING` setting needs to be enabled. Setting can be enabled in 1NCE portal [Device integrator](/docs/v2/1nce-os/1nce-os-device-integrator/).
![LwM2M Passive Reporting setting](/img/1nce-os/1nce-os-lwm2m/lwm2m-data-handling/lwm2m-passive-reporting.png)
The setting can be enabled also with a [management API call](/api/1nce-os/patch-settings/) ```shell curl --request PATCH \ --url https://api.1nce.com/management-api/v1/settings/1nceos/LWM2M_PASSIVE_REPORTING \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data '{"state": "ENABLED"}' ``` ## Reporting Example Suppose the used device support LwM2M object IDs 6 (Location) and 7 (Connectivity Statistics). Based on the registration and registration update, the LwM2M server would read all resources from objects 6 and 7 of the given client device. ## Reporting Interval By default, the registration lifetime and thus the update proposed by the LwM2M bootstrap server is **ONE day**. This would result in infrequent data updates when using passive reporting. To change this parameter to a higher registration update frequency, the LwM2M client needs to update the registration update frequency, though it should not exceed 1 day. *** # Action API With the Action API you get the possibility to automate actions in your device. Your device has to be registered on the LwM2M-Server. It is supporting following actions: * Read * Write * Execute * Observe (Defined as start and end) The actions are processed by an asynchronous API. To receive the results of your actions (read & observe), you can use the [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/). If your requests fail, you can see the messages in the [Admin Logs](/docs/v2/1nce-os/1nce-os-admin-logs/). Messages are forwarded to your cloud integrations as well when they are configured. For more information about the Action API visit the [Device Controller](/docs/v2/1nce-os/1nce-os-device-controller/). Example Request (Within this example checking the state of a LED): ```shell curl --request POST \ --url https://api.1nce.com/management-api/v1/integrate/devices/821756382750126453/actions/LWM2M \ --header 'accept: application/json' \ --header 'authorization: Bearer {token}' \ --header 'content-type: application/json' \ --data '{ "action": "read", "resourceAddress": "/3311/0/5850" }' ``` This will be the result of such message you will find in the Cloud Integrator or Device Inspector. ```json { "/3311/0/5850": false } ``` This means that the LED is off. More codes for resourceAddress can be found [here](https://technical.openmobilealliance.org/OMNA/LwM2M/LwM2MRegistry.html). --- # Device Locator Integration Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/ # LwM2M Integration with Location Service LwM2M Server will automaticaly forward GPS data to [Device locator](/docs/v2/1nce-os/1nce-os-device-locator/), if GPS data will be provided in following [OMA](https://raw.githubusercontent.com/OpenMobileAlliance/lwm2m-registry/prod/6.xml) resource addresses: * `/6/0/0` (latitude, Float) * `/6/0/1` (longitude, Float) * `/6/0/5` (timestamp, Time). Not mandatory. GPS data can be: * Visualized in the 1NCE OS portal [Device inspector](/docs/v2/1nce-os/1nce-os-device-inspector/device-inspector-features-limitations/) & [Device locator](/docs/v2/1nce-os/1nce-os-device-locator/) tabs. * Forwarded to [Cloud integrator](/docs/v2/1nce-os/1nce-os-cloud-integrator/). * Used via [API](/docs/v2/1nce-os/1nce-os-device-locator/device-locator-api/).
![Location data from LwM2M Device in Historian](/img/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/lwm2m-gps-location-payload.png)
![GPS Location in Device Locator from LwM2M data](/img/1nce-os/1nce-os-lwm2m/lwm2m-device-locator-integration/lwm2m-gps-location-map.png)
--- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-features-limitations/ # 1NCE LwM2M Interfaces At the base for the LwM2M protocol stack lies the client (e.g., IoT device) and the LwM2M server infrastructure. ## Bootstrap Server The [1NCE Bootstrap Service](/docs/v2/1nce-os/1nce-os-lwm2m/lwm2m-bootstrapping/) for LwM2M serves as a fully automated management entity for keys, access control, and configuration required to enroll an IoT device with the 1NCE LwM2M Service. This component is based in the background on the [Device Authenticator](/docs/v2/1nce-os/1nce-os-device-authenticator/) Service to automate the LwM2M bootstring with a 1NCE SIM card. ## LwM2M Server Once a connected IoT LwM2M device completed the bootstrapping process, a device can connect and register to the 1NCE LwM2M Server. This registration lets the LWM2M server know of the connected IoT device existence and its registered capability. ## Integration Test If an IoT device is registered with the 1NCE LwM2M Server, the individual device can be [tested](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-test-endpoints/#testing-the-endpoint) in the Device Integrator. If the LwM2M Integration is setup, the connection can be tested with any device. Select one of the preferred Blueprints. More information about the Blueprints can be found ind [1NCE SDK & Blueprints](/docs/v2/1nce-os/1nce-os-sdk-blueprints/). The ICCID of the device used for testing and optional the Pre-shared Key (PSK) is needed for the test setup. After setting up the testbed, a message has to be sent from the IoT SIM device. Please be aware that it can take up to 30 seconds to be received. ## LwM2M Data Reporting The 1NCE LwM2M Service enables registered devices to report information to the LwM2M server. All messages are forwarded and stored in the [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/). This service stores the received information and provides data for the visualization via the management user interface and regular event updates via the management API. *** # Features * Using 1NCE SIM connectivity, LwM2M is not bound to any specific Radio Network Type (RAT) and will work with any available communication (2G, 3G, 4G, NB-IoT, CAT-M). * The 1NCE LwM2M Service uses the Device Inspector to store the current and past device states. Further the 1NCE admin logs stores the LwM2M messages received from any registered and connected device. The state and message information can be retrieved using the management user interface or the management API. * The communication with the 1NCE LwM2M server is secured via DTLS using Pre-Shared Keys (PSK). The PSK is regenerated for each device registration. * All Open Mobile Alliance (OMA) publicly defined LwM2M objects are supported. To see the full list, please reference the OMA lwm2m-registry. * Custom LwM2M object support is available upon request. Please contact [1NCE support](https://www.1nce.com/en-eu/support/contact) and submit the object definition XML files. The following requirements apply: - The object IDs must fall within an OMNA Vendor Bulk Reservation assigned to the organization (refer to [OMNA Vendor Bulk Reservations registry](https://www.openmobilealliance.org/specifications/registries/vendor-bulk-reservations)). - The object definition must be validated against the declared OMA LwM2M XML schema. Supported schemas are [LWM2M.xsd](http://openmobilealliance.org/tech/profiles/LWM2M.xsd) and [LWM2M-v1_1.xsd](http://www.openmobilealliance.org/tech/profiles/LWM2M-v1_1.xsd). * Bootstrapping can be performed either by CoAP or CoAPs (with PSK). *** # Limitations * LwM2M Endpoints are required to be [activated](/docs/v2/1nce-os/1nce-os-device-integrator/), otherwise 1NCE LwM2M bootstrap server will not authorize devices. * LwM2M clients used with the 1NCE Service need to support v1.1 at least partially. * All LwM2M clients are required to do the bootstrapping process in order to access the 1NCE\ LwM2M server. A direct connection to the server is not possible. * If the LwM2M client device loses the connection to the LwM2M server (e.g., network reregistration, time-outs, device sleep, etc.), it needs to initiate the bootstrapping once process again. * LwM2M action API is asynchronous. Customers will not receive direct feedback from the device. --- # Plugin System Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/
![1NCE OS Plugin System](/img/1nce-os/1nce-os-plugins/plugin-system.png)
Plugins extend the capabilities of the 1NCE platform with services provided by 3rd party vendors. You can enable additional functionality by installing a plugin.
![Plugin System in 1NCE.com portal](/img/1nce-os/1nce-os-plugins/plugins-overview.png)
Available plugins: * **Datacake** - Device and Network data visualization in pre-made or custom dashboards. * **Mender** - Firmware Over-the-Air Management. * **Tartabit** - IoT Bridge with Azure, AWS, and GCP. * **Memfault** - Device Observability with Fault Diagnostics and Log management. --- # Azure Integration Plugin by Tartabit Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/ ## Description Tartabit IoT Bridge 1NCE OS Plugin swiftly integrates LPWAN devices provisioned on the 1NCE network and 1NCE OS, with customer applications running on major cloud platforms like Azure, AWS, and GCP. IoT Bridge ensures seamless connectivity via a low/no-code environment, enabling rapid deployment of production-grade IoT solutions. IoT Bridge alleviates the need to host custom servers and self-managed infrastructure. Service integrations include: **Azure** - IoT Hub, IoT Central, Digital Twin, CosmosDB, Data Explorer, Event Hub, Service Bus, Log Analytics, SQL, Maps **AWS** - IoT Core, Kinesis, Firehose, SQS, DocumentDB, DynamoDB, RDS **GCP** - Pub/Sub, Firebase, Cloud SQL, Maps **Open-source** - Kafka, AMQP, RabbitMQ, MQTT, webhooks Bottom line, if you are trying to build a world class Internet of Things solution based on LWPAN technologies then IoT Bridge, the industry’s easiest to use, easiest to buy, and easiest to deploy cloud gateway, will accelerate your time to market and reduce your development costs. ## Pricing 1NCE Plugins allow you to start at no cost. Azure Integration plugin by Tartabit provides a 1 month free trial plan. To continue with more features and benefits, please visit the Azure Marketplace and select the right [plan](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/tartabitllc1600893492587.tartabit-iot-bridge?tab=PlansAndPrice) for your business. ## Start Using To start using the 1NCE OS Plugin with Tartabit IoT Bridge you first need to create the service in Tartabit side. For that, please refer to [HTTP Connector](https://docs.tartabit.com/en/Topics/HTTP-Connector). Starting from the main page of Tartabit IoT Bridge, choose _List_ under _Services_ in the left menu, then _New Service_ and finally complete the form for a **HTTP Connector** Service Model. Only Service name, key and model are required. **Keep the Webhook Secret because it is necessary for creating the plugin in 1NCE OS system**. To finish the configuration in 1NCE OS you can choose one of the two options described below. :::warning Please note that by installing this plugin, you are aware that **Data from any device is shared with Tartabit, regardless of whether it is configured on Tartabit or not**. ::: # Tartabit Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Tartabit".
![Tartabit Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/Plugins-new-icon.png)
To install a Tartabit Plugin you should provide both Webhook Secret and the Server Domain from Tartabit.
![Tartabit plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/plugins-new-installation.png)
# Tartabit plugin installation via API ## Plugin Installation The Tartabit plugin can be created via the `partners` API by using "TARTABIT" partner in the [API Explorer](/api/). Both the Webhook Secret and the Server Domain from Tartabit should be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/TARTABIT/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "serverDomain": "bridge-us.tartabit.com", "webhookKey": "secretKey" }' ``` ## Plugin failure event There is possibility that data forwarding from the 1NCEOS to the Tartabit system can fail due to misconfiguration or temporary downtime. In that case you will see following `Error` Admin Log:
![Plugin Disabled Admin Log](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/plugin-admin-log.png)
You can use similar approach to the [Cloud Integrations failure monitoring](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/#cloud-integrations-failure-monitoring) , only for Plugins Cloud Integrator `Error` event will be following: ```json { "received": "1762419188874", "id": "1-690c61f4-e57d85442c1fee9340783e17", "type": "ERROR", "error": { "payloadExists": false, "description": "One of your plugins has failed. Please check the plugins section of 1NCE OS", "id": "3568Vyh2vh2uCIcFrrMyv6xRoIf", "type": "INTEGRATION", "message": "CloudIntegrator[PluginDisabled]" }, "version": "1.0.0" } ``` In such cases you should investigate if Tartabit system is working fine and if everything is fine trigger plugin Restart using [Restart a failed plugin by installation ID](/api/1nce-os/restart-a-failed-plugin-by-installation-id/) API endpoint or in the Frontend Tartabit plugin details page. ## Integration Restart, Get or Uninstall endpoints To restart, get, or uninstall your Tartabit integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Outcome of successful configuration ## Services List If the configuration is successful, events should appear in the Tartabit services list history.
![Services List](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/tartabit-services.png)
## Event viewer All event details can be found under Triggers/Event Viewer.
![Event viewer](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-azure-integration-tartabit/tartabit-event-viewer.png)
--- # Data Visualization Plugin by Datacake Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/ ## Description Elevate your IoT experience with the Datacake Plugin, a one-click solution that effortlessly connects the Datacake IoT platform with 1NCE OS. This intuitive plugin automatically lists devices operating on 1NCE OS within Datacake, streamlining device management. Adding a device is as simple as a click, unlocking a suite of features including pre-set dashboards for real-time monitoring and analysis. Designed for efficiency and ease of use, the Datacake Plugin is the ideal tool for enhancing your IoT ecosystem. ## Pricing 1NCE Plugins allow you to start at no cost. Data Visualization plugin by Datacake comes with a free trial plan for up to 5 devices. You can increase the number of devices and unlock more features and benefits by selecting the right [plan](https://datacake.co/pricing) for your business. ## Start Using To start using the 1NCE OS Plugin with Datacake you first need to Add a Device on the Datacake side. For that, please refer to [1NCE OS in Datacake](https://docs.datacake.de/integrations/1nce-os). Starting from the main page of Datacake, choose _+ Add Device_ under _Devices_ in the left menu, then _Connect 1NCE Devices_. **Keep the Workspace ID because it is necessary for creating the plugin in 1NCE OS system**.
![1NCE in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake.png)
![Workspace ID in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/Datacake-workspace-id.png)
To finish the configuration in 1NCE OS you can choose one of the two options described below. After configuration is done for 1NCE OS and data flow is enabled devices should be automatically available on datacake to be configured. :::warning Please note that by installing this plugin, you are aware that **Data from any device is shared with Datacake, regardless of whether it is configured on Datacake or not**. ::: # Datacake Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Datacake".
![Datacake Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-plugin.png)
To install a Datacake Plugin you should provide the Workspace Id from Datacake.
![Datacake plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-plugin-configuration.png)
# Datacake plugin installation via API ## Plugin Installation The Datacake plugin can be created via `partners` API by using "DATACAKE" partner in the [API Explorer](/api/). Only workspaceId from Datacake should be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/DATACAKE/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "workspaceId": "00000000-0000-0000-0000-000000000000" }' ``` ## Plugin failure event There is possibility that data forwarding from the 1NCEOS to the Datacake system can fail due to misconfiguration or temporary downtime. In that case you will see following `Error` Admin Log:
![Plugin Disabled Admin Log](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/plugin-admin-log.png)
You can use similar approach to the [Cloud Integrations failure monitoring](/docs/v2/1nce-os/1nce-os-cloud-integrator/cloud-integrator-failure-event/#cloud-integrations-failure-monitoring) , only for Plugins Cloud Integrator `Error` event will be following: ```json { "received": "1762419188874", "id": "1-690c61f4-e57d85442c1fee9340783e17", "type": "ERROR", "error": { "payloadExists": false, "description": "One of your plugins has failed. Please check the plugins section of 1NCE OS", "id": "3568Vyh2vh2uCIcFrrMyv6xRoIf", "type": "INTEGRATION", "message": "CloudIntegrator[PluginDisabled]" }, "version": "1.0.0" } ``` ## Integration Restart, Get or Uninstall endpoints To restart, get, or uninstall your Datacake integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Outcome of successful configuration If the configuration is completed in Datacake dashboards for the device fleet can be created for data visualization.
![Device fleet in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/datacake-data-fleet.png)
![Datacake dashaboard](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-data-visualization-datacake/Datacake-dashboards.png)

Datacake dashboard

--- # Device Observability Plugin by Memfault Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/ ## Description Memfault provides observability purpose-built for devices. Compatible with constrained microcontroller-based devices to complex Linux and Android systems, Memfault helps embedded development teams understand exactly how their devices perform in the field, and find and fix faults fast. **Fault Diagnostics**: Automatically capture diagnostics data every time your devices experience a crash or unexpected error. Diagnose and debug faults happening in the field within hours, not days or weeks.\ **Log Management**: Automatic log storage, collection, and analysis designed for devices, not servers and apps. Save hours with every investigation and turn your logs into a tool for fleet-wide insights.\ **Fleet Health Monitoring**: Monitor the health of your fleet in real-time with built-in tools for comparison between software versions, hardware versions, and more. We handle the data collection and processing, you get the insights.\ **Product Analytics**: Understand product usage, performance, and reliability using real-world data. Collect product usage data from every device in your fleet even when they aren’t connected so there are no gaps in your data and no more guessing. ## Pricing 1NCE OS Plugins allow you to start at no cost. The Device Observability plugin by Memfault has a free trial plan for up to 10 devices. You can increase the number of devices and unlock more features and benefits by selecting the right [plan for your business](https://memfault.com/pricing/). ## Start Using To install Plugin in 1NCE OS you can choose one of the two options described below. After configuration is done you can use the [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo) from 1NCE OS to showcase Memfault Plugin features and understand the capabilities of 1NCE OS SDK. :::warning Please note that during Memfault plugin installation your Organization's email address will be used for the new Memfault account. You will need access to this email to receive confirmation email from Memfault after Sign up. Please note that by installing this plugin, you are aware that **data is shared with Memfault**. ::: # Memfault Plugin Installation via Frontend ## Plugin Installation The Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Memfault."
![Memfault Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-tile.png)
There is no need to provide any extra information, so you can immediatelly proceed with the installation by pressing the "Install" button on the "Plugin Details page." :::warning Please note that after pressing install button system automatically creates Memfault account with your 1NCE Organization's email address, which cannot be changed afterwards. :::
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details.png)
If plugin installation goes well you should see the "Plugin Installed" page.\ After this, you already can start sending data to the Memfault system.
![Memfault plugin installed](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-installed.png)
In the Plugin installed page, you will see the "Open Memfault Portal" button, which in the new browser tab will open your new Memfault account finalization page. The email field will be already prefilled with your 1NCE Organization's email address.
![Finalize Memfault account](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/create-memfault-account.jpg)
In case you navigate away from the "Plugin Installed" page you can still get the Memfault registration URL by navigating to the Memfault plugin details and clicking on the "Register with Memfault" link.
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details-unfinished.png)
After registration in the Memfault portal is completed you should see the following plugin details page, where we provide details about the Memfault plugin and the "Memfault portal" link to easily navigate to your Memfault account.\ If you need to uninstall the Memfault plugin it also can be done from this page. The uninstall button will only remove the plugin from the 1NCE system, in the Memfault portal account will not be deleted.
![Memfault plugin details](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/plugin-details-finished.png)
# Memfault plugin installation via API ## Plugin Installation The Memfault plugin can be created via the `partners` API by using the "MEMFAULT" partner in the [API Explorer](/api/).\ There is no need to pass any request body during the POST request. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MEMFAULT/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ ``` ## Plugin Get and Uninstall endpoints To get details or uninstall your Memfault integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). :::warning Memfault portal Url to finalize registration can be retrieved only in the response of the Get Plugin Details endpoint. ::: # Utilizing Memfault plugin The Memfault server receives and stores debug and log data sent by your devices. 1NCE OS Memfault plugin supports CoAP/CoAPs to HTTPS proxying with seamless support for Authorization. All the data sent by the device to the 1NCE OS Coap Proxy server is proxied to the Memfault [Chunks endpoint](https://api-docs.memfault.com/#a8d3e36f-62f0-4120-9fc6-544ee04f3bb5). We automatically pass device ICCID as a device identifier to the Memfault system, so the following URI should be added in CoAP Requests `Proxy-URI`option: ``` https://chunks.memfault.com/api/v0/chunks/:iccid: ``` Additionally please remember to set the correct `Content-Format` option, for binary payloads it should be 42. To utilize proxy functionality please use one of the following endpoints for CoAP requests: * `coap://coap.proxy.os.1nce.com:5683` * `coaps://coaps.proxy.os.1nce.com:5684`. *If CoAPs is required to be used please refer to[DTLS encryption for CoAP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/#dtls-encryption-for-coap).* ### Coap to HTTPS Proxy functionality CoAP to HTTPS proxy's main functionality is to "translate" the CoAP requests to HTTPS requests and HTTPS responses to CoAP responses. As mentioned before 1NCE OS Coap Proxy for Memfault Plugin automatically replaces `:iccid:` part with the actual ICCID value before doing HTTPS request to the Memfault chunks API.\ Additionally, the Memfault plugin also retrieves and stores the Memfault project key value during plugin installation. This value then is automatically injected as a `Memfault-Project-Key` header into the HTTPS request towards Memfault Chunks API endpoint, so there is no need to manage it from the customer device side. ## Adding devices in Memfault After Memfault plugin installation is done you can utilize [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo) to start sending chunks data to the Memfault system. If chunks are processed successfully, the device will show up in the Memfault portal on the Devices page automatically with the ICCID of the 1NCE sim card used as a device serial number.
![Memfault Devices](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-device-page.png)
# Features and Limitations General [Plugins features and limitations](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations/) applies to Memfault.\ There are still some individual Features and Limitations applied to the Memfault plugin: ## Features * Seamless Memfault plugin creation without the need to prepare or enter any additional information. * Automatic Memfault authorization process in the Coap Proxy without the need to store any secrets or extra configuration on the device. ## Limitations * During Memfault account creation system will use your 1NCE Organization's email address, so there is no way to provide a custom email before plugin installation. * The device serial number in the Memfault system always is the ICCID of the 1NCE sim card. * Maximum supported payload size for Coap Proxy requests is 5120 bytes. It is suggested to send payload which is smaller than 1024 bytes in a single request to not trigger block-wise transfer. * Currently only supported Memfault proxying mode is uploading a single chunk in one request, other modes like base64-encoded chunks and multiple chunks in one request described in the [Memfault Chunks endpoint](https://api-docs.memfault.com/#a8d3e36f-62f0-4120-9fc6-544ee04f3bb5) are not supported. # Outcome of successful plugin creation After devices start to send data to the Memfault system, you can start monitoring different aspects of your device fleet.\ The Connectivity page provides useful insights like device uptime, sent data amount, and more.
![Memfault Connectivity](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-connectivity-page.png)
On the Overview page, you can display many different useful widgets.
![Memfault Overview](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/memfault-main-page.png)
More information about how to use Memfault features can be found in the [Memfault Documentation](https://docs.memfault.com/docs/platform/introduction). --- # Features & Limitations Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations/ # Features * All [Event Types](/docs/v2/1nce-os/1nce-os-cloud-integrator/#event-types) from 1NCE OS will be forwarded to Plugins.\ *Doesn't apply for Mender and Memfault plugin* * [Event Types](/docs/v2/1nce-os/1nce-os-cloud-integrator/#event-types) messages will be forwarded in JSON format.\ *Doesn't apply for Mender and Memfault plugin* # Limitations * The plugin cannot be edited. It should be reinstalled if any changes are required. * Only one entity per Plugin type is allowed to be created. --- # FOTA Management Plugin by Mender Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/ ## Description Continuously roll out new firmware to ensure compliance with security regulations like the EU Cyber Resilience Act while improving your customer experience with stability enhancements and new innovative features. Mender is the market-leading FOTA Management solution, providing secure and robust over-the-air (OTA) software updates for your entire device fleet. **Security by design**: Ensure communication, data integrity, and authenticity are verified. Trust a battle-tested solution with millions of devices under management.\ **Robustness**: Minimize the risk of bricking devices, even in cases of losing power or connectivity in the middle of the update process. Devices will always be in a known and operable state\ **Optimize**: Meet bandwidth and uptime requirements and realize up to a 90% reduction in bandwidth consumption with delta updates. Advanced scheduling and phased rollout to minimize risk of fleet interruption. ## Pricing 1NCE Plugins allow you to start at no cost. Firmware Over-The-Air Management plugin by Mender comes with a free trial plan for up to 10 devices for 12 months. You can increase the number of devices and unlock more features and benefits by selecting the right [plan](https://mender.io/product/pricing) for your business. For further inquiries about usage and pricing, please reach out to [contact@mender.io](mailto:contact@mender.io). ## Start Using To start using the 1NCE OS Plugin with Mender you first need to create a hosted Mender account and get an Organization token on the Mender side. Starting from the main page of Mender, choose *My organization* under the dropdown on your profile. **Keep the Organization token because it is necessary for creating the plugin in the 1NCE OS system**.
![Organization Token in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-Organization-Token.png)
To finish the configuration in 1NCE OS you can choose one of the two options described below. After configuration is done you can use the [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo) from 1NCE OS to showcase Mender Plugin features and understand the capabilities of 1NCE OS SDK & FOTA client. :::warning Please note that by installing this plugin, you are aware that **data is shared with Mender**. ::: # Mender Plugin Installation via Frontend ## Plugin Installation Plugin can be installed in [1NCE OS](https://portal.1nce.com/portal/customer/1nceos) portal "Plugins" tab by choosing "Mender".
![Mender Plugin](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-plugin.png)
To install a Mender Plugin you should provide the Organization Token from Mender.
![Mender plugin installation](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-plugin-configuration.png)
# Mender plugin installation via API ## Plugin Installation The Mender plugin can be created via the `partners` API by using the "MENDER" partner in the [API Explorer](/api/).\ Only the `Organization token` from the Mender is mandatory to be added to the request body. Example: ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MENDER/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "tenantToken": "abcdef123456" }' ``` If a specific user-generated Private Key and Public Key requires to be added it can be done only via API. ```curl curl --location --request POST 'https://api.1nce.com/management-api/v1/partners/MENDER/plugins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "tenantToken": "abcdef123456", "publicKey": "-----BEGIN PUBLIC KEY-----\n .. \n-----END PUBLIC KEY-----\n", "privateKey": "-----BEGIN PRIVATE KEY-----\n .. \n-----END PRIVATE KEY-----\n" }' ``` ## Integration Get or Uninstall endpoints To get details or uninstall your Mender integration via API, you can use the same endpoints you would use for a generic Plugin described in the [API Explorer](/api/). # Utilizing Mender plugin The Mender server stores and controls the deployment of software updates over the air to your devices. Mender can be used to manage devices, upload and manage software releases to the server, and create deployments to roll out software to your devices. 1NCE OS mender plugin supports CoAP/CoAPs to HTTPS proxying with seamless support for Authorization. The HTTPs [Mender endpoints](https://docs.mender.io/api/#device-apis) should be added in CoAP Requests Proxy-URI options. To utilize proxy functionality please use one of the following endpoints for CoAP requests: * `coap://coap.proxy.os.1nce.com:5683/mender` * `coaps://coaps.proxy.os.1nce.com:5684/mender`.\ *If CoAPs is required to be used please refer to[DTLS encryption for CoAP](/docs/v2/1nce-os/1nce-os-device-integrator/device-integrator-coap/#dtls-encryption-for-coap).* ### Coap to HTTPS Proxy functionality CoAP to HTTPS proxy's main functionality is to "translate" the CoAP requests to HTTPS requests and HTTPS responses to CoAP responses. Mender Plugin provides additional logic for [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) and ensures Authorization header injection for other Mender endpoints. * Whenever [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) is used for POST requests, 1NCE OS will generate the correct request body required for authentication and store the returned JWT token in the system for future use. **Please note that renewing the JWT token requires calling the endpoint once again**. Post request body example: ``` { "id_data": "{\"iccid\":\"1234567890123456789\"}", "pubKey": "-----BEGIN PUBLIC KEY-----\n .. \n-----END PUBLIC KEY-----\n", "tenant_token": "abcdef123456=" } ``` * For any other request where [Mender endpoints](https://docs.mender.io/api/#device-apis) are being used in Proxy-URI options, the JWT token will be added as an additional Authorization header for HTTPS request. ``` { "Authorization": "Bearer 'JWT_TOKEN'" } ``` * If [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) was never called and JWT token is not present in 1NCE OS, then the request will be proxied without the Authorization header. ## Adding devices in Mender By proxying the POST request to [Mender auth endpoint](https://docs.mender.io/api/#device-api-device-authentication) device would show up in mender as "Pending". The device needs to be accepted by selecting "Accept device".
![Pending Device in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-Device-Pending.png)
![Accepting Device in Mender](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Mender-device-acceptance2.png)
## Release, Deployment creation To use the 1NCE OS Plugin for Release and deployment management in Mender, please refer to [Demo script for zephyr](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo) from 1NCE OS. Examples of Artifact creation, Release, and Deployment management are provided. # Features and Limitations General [Plugins features and limitations](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-features-limitations/) applies to Mender. There are still some individual Limitations applied for Mender: ## Limitations * Only mender endpoints are allowed to be proxied. The following endpoints in CoAP Request Proxy-URI options are allowed for Mender Plugin:\ `hosted.mender.io`\ `eu.hosted.mender.io` * Public key and Private key can be provided only via API. Keys should be a pair and they should be provided in `PEM` format. The public key max allowed string length is 1000 chars, Private key max allowed string length is 3000 chars. * Currently only `RSA PKCS1` and `RSA PKCS8` private and public key types are supported. Other types `ECDSA` and `ED25519` are not supported for now. # Outcome of successful configuration ## Device List If the configuration is completed devices should be accepted and available on the Mender devices list.
![Device fleet in Datacake](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/mender-device.png)
## Deployment status In the case of an active deployment, it should be possible to track deployment statuses such as 'downloading,' 'installing,' 'success,' and other relevant [statuses](https://docs.mender.io/api/#management-api-deployments-list-all-devices-in-deployment-responses).
![Deployment with status 'installing'](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Installing.png)
In device deployment history it should be available to see all deployments.
![Device deployment history](/img/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/Deployment-log.png)
--- # 1NCE SDK & Blueprints Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-sdk-blueprints/
![](/img/1nce-os/1nce-os-sdk-blueprints/001.png)
1NCE offers different Blueprints and SDKs to allow customers a seamless setup and use of all features as part of 1NCE OS. ## 1NCE SDK The 1NCE SDK is an open-source, MIT-licensed, C SDK which can be integrated into the customer IoT devices firmware. It contains functions to authenticate against the 1NCE OS managed cloud service and to compress data for use with Energy Saver.\ The 1NCE SDK can be downloaded at: [https://github.com/1NCE-GmbH/1nce-iot-c-sdk](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) ## Blueprints Blueprints are open-source, MIT-licensed code repositories for embedded platforms. We offer onboarding scripts like the FreeRTOS onboarding blueprint to guide through all our features that 1NCE OS offers. With examples and code, we hope to make the setup smooth and simple. * [FreeRTOS Blueprint](/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/) * [Zephyr Blueprint](/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/) * [Arduino Blueprint](/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-arduino/) --- # Arduino Blueprint Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-arduino/ # 1NCE Arduino Blueprint ## Overview 1NCE Arduino blueprint provides an overview of various features of 1NCE OS including Device Authenticator, IoT Integrator and Energy Saver. In combination with 1NCE SDK. ## Supported Boards The Blueprint is compatible with [Arduino Portenta H7](https://docs.arduino.cc/hardware/portenta-h7) and [Arduino Portenta H7 lite ](https://docs.arduino.cc/hardware/portenta-h7-lite) (running Mbed OS), attached to [Portenta Cat. M1/NB IoT GNSS Shield](https://docs.arduino.cc/hardware/portenta-cat-m1-nb-iot-gnss-shield). ## 1NCE IoT C SDK Integration [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) is a collection of C source files that can be used to connect and benefit from different services from 1NCE OS. The SDK is integrated with the blueprint through UDP & Log interfaces. ## 1NCE Arduino blueprint - UDP Demo ### Overview 1NCE Arduino UDP Demo allows customers to communicate with 1NCE endpoints via UDP Protocol, and it can send compressed payload using the Energy Saver feature. ### Using 1NCE Energy saver The demo can send optimized payload using 1NCE Energy saver. This feature is enabled by default with the following definition in `nce_demo_config.h` ``` #define ENABLE_NCE_ENERGY_SAVER ``` The energy saver template used in the demo can be found in `extras/template.json` ### Configuration options The configuration options for UDP sample are: `NCE_UDP_ENDPOINT` is set to 1NCE endpoint. `NCE_UDP_PORT` is set by default to the 1NCE UDP endpoint port 4445. `NCE_UDP_DATA_UPLOAD_FREQUENCY_SECONDS` the interval between UDP packets. `NCE_PAYLOAD` Message to send to 1NCE IoT Integrator. `NCE_PAYLOAD_DATA_SIZE` Used when 1NCE Energy Saver is enabled to define the payload data size of the translation template. ## 1NCE Arduino blueprint - CoAP Demo ### Overview 1NCE Arduino CoAP Demo allows customers to establish a secure communication with 1NCE endpoints via CoAPs after receiving DTLS credentials from Device Authenticator using the SDK. It can also send compressed payload using the Energy Saver feature. ### Secure Communication with DTLS using 1NCE SDK By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. ### Using 1NCE Energy saver The demo can send optimized payload using 1NCE Energy saver. This feature is enabled by default with the following definition in `nce_demo_config.h` ``` #define ENABLE_NCE_ENERGY_SAVER ``` The energy saver template used in the demo can be found in `extras/template.json` ### Unsecure CoAP Communication To test unsecure communication, disable the device authenticator by removing the following definition from `nce_demo_config.h` ``` #define ENABLE_NCE_DEVICE_AUTHENTICATOR ``` ### Configuration options The configuration options for CoAP sample are: `NCE_COAP_ENDPOINT` is set to 1NCE endpoint. `NCE_COAP_PORT` is set automatically based on security options (with/without DTLS). `NCE_COAP_URI_QUERY` the URI Query option used to set the MQTT topic for 1NCE IoT integrator. `NCE_COAP_DATA_UPLOAD_FREQUENCY_SECONDS` the interval between CoAP packets. `NCE_PAYLOAD` Message to send to 1NCE IoT Integrator. `NCE_PAYLOAD_DATA_SIZE` Used when 1NCE Energy Saver is enabled to define the payload data size of the translation template. ## 1NCE Arduino blueprint - LwM2M Demo ### Overview 1NCE Arduino LwM2M Demo allows customers to communicate with 1NCE endpoints via LwM2M Protocol. LwM2M Actions can be tested using the [Action API](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/). For example: * To get the firmare update object info, send a `read` action to object `/5`. ### Configuration options The configuration options for LwM2M sample are: `NCE_ICCID` the ICCID of 1NCE SIM Card. `LWM2M_ENDPOINT` is set to 1NCE endpoint. DTLS is enabled by default. To use DTLS, bootstraping PSK should be defined in `LWM2M_BOOTSTRAP_PSK`. It can be configured while testing the LwM2M integration (From the Device integrator), or from the API [Create Pre-Shared Device Key](/api/1nce-os/create-pre-shared-device-key/). ### Unsecure LwM2M Communication To test unsecure communication, disable the device authenticator by removing the following definition from `nce_demo_config.h` ``` #define LwM2M_ENABLE_DTLS ``` --- # FreeRTOS Blueprint Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/ 1NCE FreeRTOS BluePrint demonstrates the usage of various IoT protocols inculuding CoAP, LwM2M, and UDP with cellular connectivity. In combination with 1NCE SDK for the integration of 1NCE OS tools. # Overview 1NCE FreeRTOS BluePrint release integrates 1NCE SDK to benefit from different 1NCE OS tools including device Authentication and Energy Saver, with the addition of a static library for CoAP Protocol ([Lobaro CoAP](https://www.lobaro.com/portfolio/lobaro-coap/)) and LwM2M ([Wakaama](https://www.eclipse.org/wakaama/)). This Repository present examples of simple code: * CoAP protocol * CoAPs protocol (with DTLS security using Pre-shared key) * UDP Demo * LwM2M with Bootstrap * LwM2M without Bootstrap Additionally, All the Demos have the Energy Saver feature as a Flag that can be enabled to test this feature. # Getting started ## Prerequisites * B-L475E-IOT01A2 STM32 Discovery kit IoT node connected to BG96 (LTE Cat M1/Cat NB1/EGPRS modem) through X-NUCLEO-STMODA1 expansion board. * [1NCE SIM Card.](https://shop.1nce.com/portal/shop/) * STM32CubeIDE from [https://www.st.com/content/st\_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-ides/stm32cubeide.html](https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-ides/stm32cubeide.html) * STM32 ST-LINK utility from [https://www.st.com/en/development-tools/stsw-link004.html](https://www.st.com/en/development-tools/stsw-link004.html) * Upgrade the modem BG96 to the latest firmware. ([https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem\_FW](https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW))\ **Note:** Download the modem FW flasher tool (QFlash) from this url: [https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem\_FW](https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW) this tools taked from quectel from the web site listed in the official documentation. ## Cloning the Repository After navigating to your workspace Clone the repository using HTTPS\: ``` $ git clone https://github.com/1NCE-GmbH/blueprint-freertos.git --recurse-submodules ``` Using SSH: ``` $ git clone git@github.com:1NCE-GmbH/blueprint-freertos.git --recurse-submodules ``` If you have downloaded the repo without using the --recurse-submodules argument, you need to run: ``` git submodule update --init --recursive ``` * Import the project in STM32Cube. ## Building Sample Setup your demo want to use by going to config\_files/aws\_demo\_config.h define one of three demos exist (by default `CONFIG_COAP_DEMO_ENABLED`) ``` CONFIG_COAP_DEMO_ENABLED CONFIG_UDP_DEMO_ENABLED CONFIG_LwM2M_DEMO_ENABLED ``` ## Sample Demos ### COAP Demo without DTLS 1NCE FreeRTOS BluePrint allows customers to communicate with 1NCE endpoints via CoAP and use of all features as part of the 1NCE OS. COAP POST request:\ In this Section, the following steps are executed: * Register to the Network. * Perform a DNS Resolution. * Create a socket and connect to Server * Create Confirmable CoAP POST with Query option * Create Client Interaction and analyze the response (ACK) * Validate the response. * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_COAP_DEMO_ENABLED ``` * The onboarding script configuration can be found in blueprint-freertos\\vendors\\st\\boards\\stm32l475\_discovery\\aws\_demos\\config\_files\\nce\_demo\_config.h in the root folder of the blueprint or /aws\_demos/config\_files/nce\_demo\_config.h in IDE. ``` #define PUBLISH_PAYLOAD_FORMAT "Welcome to 1NCE's Solution" #define democonfigCLIENT_ICCID "" #define COAP_ENDPOINT "coap.os.1nce.com" #define configCOAP_PORT 5683 #define democonfigCLIENT_IDENTIFIER "t=test" #if ( configCOAP_PORT == 5684 ) #define ENABLE_DTLS #endif /* Enable send the Information to 1NCE's client support */ #if defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 ) #ifndef ENABLE_DTLS #define ENABLE_DTLS #endif #endif ``` ### CoAPs with DTLS For the DTLS Support the default Port is 5684 and automatically defines the `ENABLE_DTLS` as an additional define The CoAP DTLS performs 3 main tasks from the [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) : * Send the Device Authenticator Request * Get the Response * Process the Response and give the DTLS identity and PSK to the application code. ### UDP Demo 1NCE FreeRTOS Blueprint allows customers to communicate with 1NCE endpoints via UDP and use all features as part of the 1NCE OS. * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_UDP_DEMO_ENABLED ``` * The onboarding script configuration can be found in blueprint-freertos\\vendors\\st\\boards\\stm32l475\_discovery\\aws\_demos\\config\_files\\nce\_demo\_config.h in the root folder of the blueprint or /aws\_demos/config\_files/nce\_demo\_config.h in IDE. ``` #define UDP_ENDPOINT "udp.os.1nce.com" #define UDP_PORT 4445 #define CONFIG_NCE_ENERGY_SAVER //the message you want to publish in IoT Core #define PUBLISH_PAYLOAD_FORMAT "Welcome to 1NCE's Solution" #define democonfigCLIENT_ICCID "" ``` ### LwM2M Demo The LWM2M support is provided using Eclipse Wakaama library communicating with a Leshan LWM2M server * Setup the Demo runner in file (config\_files/aws\_demo\_config.h) ``` #define CONFIG_LwM2M_DEMO_ENABLED ``` * The client that has registered on the LwM2M server, can send data by doing the Send operation. More specifically, it is used by the Client to report values for Resources and Resource Instances of known LwM2M Object Instance(s) to the LwM2M Server.\ To use this feature in our Blueprint: remove/ comment #define LWM2M\_PASSIVE\_REPORTING and define sending object (e.g. /4/0 here). The LWM2M endpoint and the client name can be configured in config\_files/nce\_demo\_config.h as follows: ``` #define LWM2M_ENDPOINT "lwm2m.os.1nce.com" #define ENABLE_DTLS #define LWM2M_CLIENT_MODE #define LWM2M_BOOTSTRAP #ifdef ENABLE_DTLS char lwm2m_psk[30]; char lwm2m_psk_id[30]; #endif #define LWM2M_SUPPORT_SENML_JSON #define LWM2M_LITTLE_ENDIAN #define LWM2M_SUPPORT_TLV #define LWM2M_COAP_DEFAULT_BLOCK_SIZE 1024 #define LWM2M_VERSION_1_1 #define LWM2M_SINGLE_SERVER_REGISTERATION //#define LWM2M_PASSIVE_REPORTING #if defined(LWM2M_PASSIVE_REPORTING) #define LWM2M_1NCE_LIFETIME 30000 #else #define LWM2M_OBJECT_SEND "/4/0" #endif ``` ## Troubleshooting Demo: > This feature is limited to Users and Accounts who have already accepted our 1NCEOS Addendum to the 1NCE T\&Cs. It is a one-time action per 1NCE Customer Account. Please log into the 1NCE Customer Portal as Owner or Admin, navigate to the 1NCEOS, and accept the Terms. If you don't see anything to accept and get directly to the Dashboard of the 1NCEOS, you are ready to go! > > N.B: The SMS and Data Consumed for the Troubleshooting are counted against the Customers own Volume of the SIM Card. This initial version's main target is to allow customers to connect their Things and automate the network debugging faster and more reliably. This will also reduce the workload on our Customer facing support teams and will also allow us to focus on further common issues. * Go to config\_files/nce\_demo\_config.h --> enable the flag TROUBLESHOOTING (Troubleshooting Example with/without DTLS in primary Flow and SMS as an alternative) ``` #define COAP_ENDPOINT "coap.os.1nce.com" #define configCOAP_PORT 5684 #define democonfigCLIENT_IDENTIFIER "t=test" #if ( configCOAP_PORT == 5684 ) #define ENABLE_DTLS #endif /* Enable send the Information to 1NCE's client support */ #define TROUBLESHOOTING #if defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 ) #ifndef ENABLE_DTLS #define ENABLE_DTLS #endif #endif ``` * run the demo : the demo will send the information to the coap endpoint as a first step if No ACK comes then an SMS to 1NCE portal with the required pieces of information. ## Primary Case ![Troubleshooting from the coap endpoint](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/fd91e61-troubleshootingcoap.png) ## Fallback ![Troubleshooting from Portal](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-freertos/ddf7711-troubleshootingcoap2.png) for more information on the troubleshooting | Parameter | Description | | --- | --- | | Radio Access Technology | * GSM * LTE * CATM1 * NBIOT * Otherwise: NULL | | Public Land Mobile Network (PLMN) information | * Mobile Country Code * Mobile Network Code | | Registered Network (RN) | * Registered network operator cell Id. * Registered network operator Location Area Code. * Registered network operator Routing Area Code. * Registered network operator Tracking Area Code. | | Reject CS ((Circuit Switched) registration status) | * : Table 2. * : 0: 3GPP specific Reject Cause. Manufacture specific. : Circuit Switch Reject cause. | | Reject PS ((Packet Switched) registration status) | * : Table 2. * : 0: 3GPP specific Reject Cause. Manufacture specific. : Circuit Switch Reject cause. | | Signal Information | * Received Signal Strength Indicator (RSSI) in dBm. * LTE Reference Signal Received Power (RSRP) in dBm * LTE Reference Signal Received Quality (RSRQ) in dB. * LTE Signal to Interference-Noise Ratio in dB. * Bit Error Rate (BER) in 0.01%. * A number between 0 to 5 (both inclusive) indicating signal strength. |

Table 1. Key Feature of Troubleshooting Message

| Number | description | | :----: | :---------------------------------------------------------------- | | 0 | CELLULAR NETWORK REGISTRATION STATUS NOT REGISTERED NOT SEARCHING | | 1 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED HOME | | 2 | CELLULAR NETWORK REGISTRATION STATUS NOT REGISTERED SEARCHING | | 3 | CELLULAR NETWORK REGISTRATION STATUS REGISTRATION DENIED | | 4 | CELLULAR NETWORK REGISTRATION STATUS UNKNOWN | | 5 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED ROAMING | | 6 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED HOME SMS ONLY | | 7 | CELLULAR NETWORK REGISTRATION STATUS REGISTERED ROAMING SMS ONLY | | 8 | CELLULAR NETWORK REGISTRATION STATUS ATTACHED EMERG SERVICES ONLY | | 9 | CELLULAR NETWORK REGISTRATION STATUS MAX |

Table 2. Network Registration Status

# Asking for Help The most effective communication with our team is through GitHub. Simply create a [new issue](https://github.com/1NCE-GmbH/blueprint-freertos/issues/new/choose) and select from a range of templates covering bug reports, feature requests, documentation issue, or Gerneral Question. --- # Zephyr Blueprint Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/ # 1NCE Zephyr blueprint ## 🧭 Overview The **1NCE Zephyr Blueprint** is a reference application that showcases how to integrate and use various 1NCE OS features with [Zephyr RTOS](https://zephyrproject.org/), including: * ✅ **Device Authenticator** * 📡 **IoT Integrator** * 🔋 **Energy Saver** * 📥 **Device Controller** for UDP and CoAP-based downlink and real-time remote interaction * 🧩 **Plugin Integrations** with partners like [Mender](https://mender.io) for FOTA and [Memfault](https://memfault.com) for device observability It is based on the **1NCE IoT C SDK** and runs on Nordic Semiconductor boards. The Zephyr OS is a scalable, secure, real-time operating system designed for resource-constrained embedded devices — from smart sensors to full-featured gateways. *** ## 🧱 Supported Boards The demo supports the following Nordic boards: * [nRF9151 Development Kit](https://www.nordicsemi.com/Products/Development-hardware/nrf9151-dk) * [nRF9160 Development Kit](https://www.nordicsemi.com/Products/Development-hardware/nrf9160-dk) * [Thingy:91](https://www.nordicsemi.com/Products/Development-hardware/Nordic-Thingy-91) *** ## 🚀 Getting Started This guide walks you through: * Setting up the **1NCE IoT C SDK** * Getting the source code * Building and flashing the blueprint demo *** ### 📦 Prerequisites * [nRF Connect SDK v2.8.0](https://docs.nordicsemi.com/bundle/ncs-2.8.0/page/nrf/installation/install_ncs.html) * [Visual Studio Code](https://code.visualstudio.com/) * [West tool](https://docs.zephyrproject.org/3.1.0/develop/west/install.html) *** ## 🧩 Integrating 1NCE IoT C SDK The [1NCE IoT C SDK](https://github.com/1NCE-GmbH/1nce-iot-c-sdk) provides C-based modules to easily use 1NCE OS services. Follow these steps: 1. **Open`west.yml`:** ```bash %HOMEPATH%\ncs\v2.8.0\nrf\west.yml ``` 2. **Add the module to`name-allowlist`:**\ Ensure `nce-sdk` is listed in alphabetical order. 3. **Activate the SDK via submanifest:** Rename and edit the file: ```bash %HOMEPATH%\ncs\v2.8.0\zephyr\submanifests\example.yaml ``` ```yaml manifest: projects: - name: nce-sdk url: https://github.com/1NCE-GmbH/1nce-iot-c-sdk revision: main ``` 4. **Run West update:**\ Open a terminal (e.g., `cmd.exe` on Windows, Terminal on macOS/Linux) and run: ```bash cd %HOMEPATH%\ncs\v2.8.0 west update ``` *** ## ▶️ Running the Demo 1. **Clone the Blueprint Repository:** ```bash git clone https://github.com/1NCE-GmbH/blueprint-zephyr.git ``` 2. **Open VS Code and Launch nRF Connect Extension** 3. **Add the project:** * Click **Add Existing Application** * Choose the folder where the blueprint was cloned 4. **Create a Build Configuration:** * Select your board target, e.g.: * `nrf9160dk/nrf9160/ns` * `nrf9151dk/nrf9151/ns` * `thingy91/nrf9160/ns` 5. **Flash the board:** * Connect your board via USB * Click **Flash** or **Debug** to deploy the firmware 📖 Need help with board connection?\ 👉 [Nordic Docs: Connect Using Serial Port](https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/guides/bd_work_with_boards.html#how-to-connect-using-serial-port) *** ## 🧪 Testing Instructions for Thingy:91 To easily test the default setup on the **Thingy:91**, follow these steps using the provided binaries for the specific demo you'd like to run: 1. **Remove the plastic cover** from the Thingy:91. 2. **Connect the device to your computer** using a micro-USB cable. 3. **Enter DFU mode**: * Power off the Thingy:91. * Hold down the **black button** while switching the power back to **ON**. 4. **Open[nRF Connect for Desktop](https://www.nordicsemi.com/Products/Development-tools/nrf-connect-for-desktop)** and launch the **Programmer** tool. 5. Click **SELECT DEVICE** and choose **Thingy:91** from the dropdown list. 6. In the left panel, go to **File > Add file > Browse** and choose the appropriate `.hex` file from the `thingy_binaries` folder of your desired demo. 7. Scroll down to **Enable MCUboot** and ensure it is checked. 8. Click **Write** on the left panel, then confirm again in the **MCUboot DFU** pop-up by pressing **Write**. 9. Wait for the update to finish. A message saying **"Completed successfully"** will confirm a successful flash. ### 📂 Available Firmware for Thingy:91 * [🔐 CoAP Demo Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/nce_coap_demo/thingy_binaries) * [📡 UDP Demo Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/nce_udp_demo/thingy_binaries) * [📥 FOTA with Mender Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_fota_mender_demo/thingy_binaries) * [🛠️ Debug with Memfault Firmware](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo/thingy_binaries) :::tip For Memfault diagnostics and debugging, you should upload [zephyr.elf](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_debug_memfault_demo/thingy_binaries/zephyr.elf) file to the Memfault portal. Refer to the [Memfault documentation](https://docs.memfault.com) for instructions on setting up symbol files and debugging integration.\ For a faster getting started experience, you can directly use the documentation under [`plugin_system/nce_debug_memfault_demo`](https://github.com/1NCE-GmbH/blueprint-zephyr/tree/main/plugin_system/nce_debug_memfault_demo). ::: 📘 For more detailed device guidance, check the official [Thingy:91 Getting Started Guide](https://docs.nordicsemi.com/bundle/ncs-2.6.1/page/nrf/device_guides/working_with_nrf/nrf91/thingy91_gsg.html) *** ## 📚 Demos in This Blueprint The blueprint includes the following applications: | Demo Path | Summary | | --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `nce_coap_demo` | Secure CoAP communication using DTLS from Device Authenticator, with Energy Saver & Device Controller support | | `nce_udp_demo` | Lightweight UDP communication with compressed payloads and Device Controller | | `nce_lwm2m_demo` | LwM2M client for LED, buzzer, and sensor control over CoAP/DTLS with support for 1NCE Action API | | `plugin_system/nce_debug_memfault_demo` | Device diagnostics and crash reporting using Memfault over the 1NCE CoAP Proxy | | `plugin_system/nce_fota_mender_demo` | Firmware-over-the-air updates via Mender.io using the 1NCE CoAP Proxy and secure onboarding | *** # Sample Demos # 1NCE Zephyr blueprint - UDP Demo ## Overview 1NCE Zephyr UDP Demo allows customers to communicate with 1NCE endpoints via UDP Protocol, and it can send compressed payload using the Energy Saver feature. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – Connecting to the network * 🔵 **BLUE** – Network connection established * 🟢 **GREEN** – Message sent to 1NCE OS ## ⚡ Using 1NCE Energy Saver The demo can send optimized payload using 1NCE Energy Saver. To enable this feature, add the following flag to `prj.conf` ``` CONFIG_NCE_ENERGY_SAVER=y ``` When enabled, the device will send compressed messages based on a translation template defined in 1NCE OS portal. :::tip ### **Learn more:** See the [1NCE Energy Saver documentation](/docs/v2/1nce-os/1nce-os-energy-saver/) for details on how this feature works and how to configure templates. ::: :::info ### **Tip:** You can view incoming messages in the [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/) in the 1NCE OS portal. ::: :::tip Add the template located in `./nce_udp_demo/template/template.json` to the 1NCE OS portal, and enable it for the **UDP protocol** to ensure correct decoding of the compressed payload. ::: ## ⚙️ Configuration Options The available configuration parameters for the UDP demo: | Config Option | Description | Default | | ------------------------------------------ | -------------------------------------------------- | ----------------- | | `CONFIG_UDP_SERVER_HOSTNAME` | UDP server hostname | `udp.os.1nce.com` | | `CONFIG_UDP_SERVER_PORT` | UDP server port number | `4445` | | `CONFIG_UDP_DATA_UPLOAD_FREQUENCY_SECONDS` | Interval between UDP transmissions (in seconds) | `20` | | `CONFIG_UDP_PSM_ENABLE` | Enable LTE Power Saving Mode (PSM) | `n` | | `CONFIG_UDP_EDRX_ENABLE` | Enable LTE enhanced Discontinuous Reception (eDRX) | `n` | | `CONFIG_UDP_RAI_ENABLE` | Enable LTE Release Assistance Indication (RAI) | `n` | *** ### 🔋 Payload Configuration Depending on whether the Energy Saver feature is enabled: * If `CONFIG_NCE_ENERGY_SAVER` is **disabled**: | Config Option | Description | Default | | ---------------- | ----------------------------------- | ----------------------------------------- | | `CONFIG_PAYLOAD` | Message sent to 1NCE IoT Integrator | `{"text": "Hi, this is a test message!"}` | * If `CONFIG_NCE_ENERGY_SAVER` is **enabled**: | Config Option | Description | Default | | ------------------------------ | ----------------------------------------------- | ------- | | `CONFIG_NCE_PAYLOAD_DATA_SIZE` | Payload data size for the Energy Saver template | `10` | ## 🧠 Device Controller The **Device Controller** allows your device to receive CoAP downlink messages using the 1NCE Management API. It supports sending downlink requests that your device can process in real-time. 📘 More info: [1NCE DevHub – Device Controller](/docs/v2/1nce-os/1nce-os-device-controller/) ### 🔁 Sending a Request You can trigger a downlink using the following `curl` command: ``` curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices//actions/UDP' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "payload": "enable_sensor", "payloadType": "STRING", "port": 3000, "requestMode": "SEND_NOW" }' ``` Replace: * `` with your SIM's ICCID * `` with your [OAuth token](/api/authorization/post-access-token-post/) *** ### 📩 Request Parameters | Parameter | Description | Example | | ------------- | -------------------------------------------------------- | ----------------- | | `payload` | Data to send to the device | `"enable_sensor"` | | `payloadType` | Type of payload (`STRING`, `HEX`, etc.) | `"STRING"` | | `port` | UDP port to receive the message (`CONFIG_NCE_RECV_PORT`) | `3000` | | `requestMode` | Request mode (`SEND_NOW` or `SEND_WHEN_ACTIVE`) | `"SEND_NOW"` | *** ## 🔧 Zephyr Device Controller Configuration To enable and handle downlink messages on your device, use the following configs: | Config Option | Description | Default | | ------------------------------------- | ---------------------------------------- | ------- | | `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` | Enables the device controller feature | `y` | | `CONFIG_NCE_RECV_PORT` | UDP port to listen for incoming messages | `3000` | | `CONFIG_NCE_RECEIVE_BUFFER_SIZE` | Buffer size for incoming UDP payloads | `1024` | *** ## 📤 Zephyr Output Example When the Zephyr application receives a UDP downlink from the 1NCE API: ``` [00:00:02.996,978] [downlink_thread] NCE_UDP_DEMO: Downlink thread started... [00:00:02.997,802] [downlink_thread] NCE_UDP_DEMO: Listening on port: 3000 [00:00:11.325,683] [downlink_thread] NCE_UDP_DEMO: Received message: enable_sensor ``` ## 📦 Ready-to-Flash Firmware for Thingy:91 We provide a **prebuilt HEX file** for Thingy:91 that you can flash directly to your device for quick testing.\ No build setup is required — just flash and go. 👉 **Download:** [Thingy:91 Prebuilt HEX](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/nce_udp_demo/thingy_binaries/zephyr.signed.hex) :::warning The firmware is configured with all LTE bands enabled, which may cause a delay of several minutes during the initial network connection while scanning for available bands. This is normal. ::: *** # 1NCE Zephyr blueprint - CoAP Demo ## Overview 1NCE Zephyr CoAP Demo allows customers to establish a secure communication with 1NCE endpoints via CoAPs after receiving DTLS credentials from Device Authenticator using the SDK. It can also send compressed payload using the Energy Saver feature. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – Connecting to the network * 🔵 **BLUE** – Network connection established * 🟢 **GREEN** – Message sent to 1NCE OS ## Secure Communication with DTLS using 1NCE SDK By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. > ⚠️ **Note:** If the Pre-shared Key for DTLS is set manually, **STRING** format should be used. ## Unsecure CoAP Communication To test unsecure communication (plain CoAP), disable the device authenticator by adding the following flag to `prj.conf` ``` CONFIG_NCE_DEVICE_AUTHENTICATOR=n ``` ## ⚡ Using 1NCE Energy saver The demo can send compressed, optimized payloads using 1NCE Energy Saver. This reduces payload size and improves energy efficiency.\ Enable in `prj.conf`: ``` CONFIG_NCE_ENERGY_SAVER=y ``` When enabled, the device will send compressed messages based on a translation template defined in 1NCE OS portal. :::tip Add the template located in `./nce_coap_demo/template/template.json` to the 1NCE OS portal, and enable it for the **COAP protocol** to ensure correct decoding of the compressed payload. ::: :::tip ### **Learn more:** See the [1NCE Energy Saver documentation](/docs/v2/1nce-os/1nce-os-energy-saver/) for details on how this feature works and how to configure templates. ::: :::info ### **Tip:** You can view incoming messages in the [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/) in the 1NCE OS portal. ::: If disabled, a plain-text message will be sent instead. ## ⚙️ Configuration options The following configuration options are available for customizing the CoAP client behavior: | Config Option | Description | Default | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | `CONFIG_COAP_SAMPLE_SERVER_HOSTNAME` | CoAP server hostname | `coap.os.1nce.com` | | `CONFIG_COAP_SAMPLE_SERVER_PORT` | CoAP server port (5684 if DTLS enabled, otherwise 5683) | Auto | | `CONFIG_COAP_URI_QUERY` | URI query string used as topic parameter | `t=test` | | `CONFIG_COAP_SAMPLE_REQUEST_INTERVAL_SECONDS` | Interval between uplink messages (in seconds) | `60` | | `CONFIG_NCE_DEVICE_AUTHENTICATOR` | Enables device onboarding with 1NCE SDK | `y` | | `CONFIG_NCE_UPLINK_MAX_RETRIES` | Max retry attempts for uplink CoAP requests | `5` | | `CONFIG_NCE_DTLS_HANDSHAKE_TIMEOUT_SECONDS` | DTLS handshake timeout | `15` | | `CONFIG_NCE_MAX_DTLS_CONNECTION_ATTEMPTS` | Max DTLS failures before retrying onboarding | `3` | | `CONFIG_NCE_DTLS_SECURITY_TAG` | DTLS TAG used to store credentials on the modem | `1111` | | `CONFIG_NCE_ENABLE_DTLS` | Enables DTLS for secure CoAP communication. This is **automatically enabled** when both `ZEPHYR_NCE_SDK_MODULE` and `NCE_DEVICE_AUTHENTICATOR` are enabled. | `y` if `ZEPHYR_NCE_SDK_MODULE && NCE_DEVICE_AUTHENTICATOR`, else `n` | *** ### 🔋 Payload Configuration Depending on whether the Energy Saver feature is enabled: * If `CONFIG_NCE_ENERGY_SAVER` is **disabled**: | Config Option | Description | Default | | ---------------- | ----------------------------------- | ----------------------------------------- | | `CONFIG_PAYLOAD` | Message sent to 1NCE IoT Integrator | `{"text": "Hi, this is a test message!"}` | *** * If `CONFIG_NCE_ENERGY_SAVER` is **enabled**: | Config Option | Description | Default | | ------------------------------ | ----------------------------------------------- | ------- | | `CONFIG_NCE_PAYLOAD_DATA_SIZE` | Payload data size for the Energy Saver template | `10` | *** > ⚠️ **Note:** The default maximum length for `CONFIG_COAP_URI_QUERY` is **12 bytes**. > > To increase this limit, set: > > ```conf > CONFIG_COAP_EXTENDED_OPTIONS_LEN=y > CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE=`` > ``` ## 🧠 Device Controller The **Device Controller** allows your device to receive CoAP downlink messages using the 1NCE Management API. It supports sending downlink requests that your device can process in real-time. 📘 More info: [1NCE DevHub – Device Controller](/docs/v2/1nce-os/1nce-os-device-controller/) ### 🔁 Sending a Request Use the following `curl` command to send a CoAP request to your device: ``` curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices//actions/COAP' \ -H 'accept: application/json' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "payload": "Data to send to the device", "payloadType": "STRING", "port": , "path": "/example?param1=query_example1", "requestType": "POST", "requestMode": "SEND_NOW" }' ``` Replace: * `` with your SIM’s ICCID * `` with your [OAuth token](/api/authorization/post-access-token-post/) *** #### 📩 Request Parameters | Parameter | Description | Example | | ------------- | --------------------------------------------- | ------------------------- | | `payload` | Data to send to the device | `"enable_sensor"` | | `payloadType` | Type of payload (`STRING`, `HEX`, etc.) | `"STRING"` | | `port` | Device port to receive the message | `3000` | | `path` | Request path and optional query | `"/example?param1=query"` | | `requestType` | CoAP method to use (`POST`, `GET`, etc.) | `"POST"` | | `requestMode` | Request mode (`SEND_NOW`, `SEND_WHEN_ACTIVE`) | `"SEND_NOW"` | ## 🔧 Zephyr Device Controller Configuration If `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` is enabled: | Config Option | Description | Default | | --------------------------------------- | --------------------------------------------------------------- | ------- | | `CONFIG_NCE_ENABLE_DEVICE_CONTROLLER` | Enables the device controller feature | `y` | | `CONFIG_NCE_RECV_PORT` | UDP port to listen for incoming CoAP messages | `3000` | | `CONFIG_NCE_RECEIVE_BUFFER_SIZE` | Buffer size for CoAP message handling | `1024` | | `CONFIG_NCE_DOWNLINK_MAX_RETRIES` | Max retry attempts for setting up downlink socket | `5` | | `CONFIG_NCE_COAP_MAX_URI_PATH_SEGMENTS` | Maximum number of URI path segments to support in CoAP requests | `5` | | `CONFIG_NCE_COAP_MAX_URI_QUERY_PARAMS` | Maximum number of query parameters allowed in CoAP requests | `5` | *** ## ⚠️ CoAP Limitations > CoAP messages — including **uplink and downlink** — are subject to strict option length limitations (especially for `URI-QUERY` and extended paths).\ > Make sure to increase buffer sizes if your topic or query strings exceed the default 12 bytes using: > > ```conf > CONFIG_COAP_EXTENDED_OPTIONS_LEN=y > CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE=`` > ``` ## 📤 Zephyr Output Example When the Zephyr application receives a CoAP message from the 1NCE API: ``` [00:00:02.275,817] [downlink_thread] NCE_COAP_DEMO: Downlink thread started... [00:00:02.276,336] [downlink_thread] NCE_COAP_DEMO: Listening on port: 3000 [00:00:07.847,869] [downlink_thread] NCE_COAP_DEMO: Received 72 bytes from server [00:00:07.847,930] [downlink_thread] NCE_COAP_DEMO: Received raw data: 48 02 1e 02 98 73 d5 1f d7 3a 5a 1c b7 65 78 61 |H....s.. .:Z..exa 6d 70 6c 65 10 3d 08 70 61 72 61 6d 31 3d 71 75 |mple.=.p aram1=qu 65 72 79 5f 65 78 61 6d 70 6c 65 31 ff 44 61 74 |ery_exam ple1.Dat 61 20 74 6f 20 73 65 6e 64 20 74 6f 20 74 68 65 |a to sen d to the 20 64 65 76 69 63 65 0a | device. [00:00:07.847,961] [downlink_thread] NCE_COAP_DEMO: CoAP Header: [00:00:07.847,991] [downlink_thread] NCE_COAP_DEMO: Version: 1 [00:00:07.848,022] [downlink_thread] NCE_COAP_DEMO: Type: CON [00:00:07.848,022] [downlink_thread] NCE_COAP_DEMO: CoAP Request Method: POST (0.02) [00:00:07.848,052] [downlink_thread] NCE_COAP_DEMO: Message ID: 7682 [00:00:07.848,052] [downlink_thread] NCE_COAP_DEMO: CoAP Options: [00:00:07.848,083] [downlink_thread] NCE_COAP_DEMO: Complete Path: [00:00:07.848,114] [downlink_thread] NCE_COAP_DEMO: /example [00:00:07.848,175] [downlink_thread] NCE_COAP_DEMO: CoAP Payload (binary): 44 61 74 61 20 74 6f 20 73 65 6e 64 20 74 6f 20 |Data to send to 74 68 65 20 64 65 76 69 63 65 0a |the devi ce. [00:00:07.848,236] [downlink_thread] NCE_COAP_DEMO: sent ack: 68 44 1e 02 98 73 d5 1f d7 3a 5a 1c |hD...s.. .:Z. [00:00:07.848,632] [downlink_thread] NCE_COAP_DEMO: CoAP ACK sent successfully ``` ## 📦 Ready-to-Flash Firmware for Thingy:91 We provide a **prebuilt HEX file** for Thingy:91 that you can flash directly to your device for quick testing.\ No build setup is required — just flash and go. 👉 **Download:** [Thingy:91 Prebuilt HEX](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/nce_coap_demo/thingy_binaries/zephyr.signed.hex) :::warning The firmware is configured with all LTE bands enabled, which may cause a delay of several minutes during the initial network connection while scanning for available bands. This is normal. ::: *** # 1NCE Zephyr blueprint - LwM2M Demo ## Overview The **1NCE LwM2M Demo** enables devices to communicate with 1NCE endpoints using the **LwM2M protocol** over CoAP, with optional DTLS for secure messaging. It supports control of LEDs, buzzers, sensors, and other objects via LwM2M standard object models. On the `Thingy:91` device, LED indicators show the following statuses: * 🔴 **RED** – the device is currently connecting to the network * 🔵 **BLUE** – the device is currently bootstrapping * 🟢 **GREEN (10 seconds)** – the device is registered with 1NCE LwM2M server ### ✅ Supported Objects for LwM2M Actions 🔗 LwM2M actions can be tested using the [1NCE Action API](/api/1nce-os/create-action-request-on-specific-lw-m-2-m-device/) or from the device controller tab in 1NCE OS UI. | Object | Path(s) | Description | Supported Boards | | ------------- | -------------------------------------------------------------------- | --------------------------------------- | ---------------- | | Light Control | `/3311/0/5850` (1 Thingy:91 LED) `/3311/<0–3>/5850` (4 DK LEDS) | Boolean: LED on/off | All boards | | Light Color | `/3311/0/5706` | RGB LED color in HEX (e.g., `0xFF0000`) | Thingy:91 only | | Buzzer | `/3338/0/5850` | Boolean: Audible alert | Thingy:91 only | *** ## ⚙️ Configuration Options ### 🔐 Authentication & Server Setup | Config Option | Description | Default | | --------------------------------------------- | --------------------------------------------------------- | ------- | | `CONFIG_NCE_ICCID` | ICCID used as endpoint name and device identity | `""` | | `CONFIG_NCE_LWM2M_BOOTSTRAP_PSK` | Pre-shared key in HEX for bootstrap/auth | `""` | | `CONFIG_LWM2M_CLIENT_UTILS_SERVER` | LwM2M server URI (e.g., `coaps://lwm2m.os.1nce.com:5684`) | - | | `CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG` | Security tag for bootstrap server (credentials storage) | `1111` | | `CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG` | Security tag for main server (replaced after bootstrap) | `1112` | | `CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME` | Default LwM2M Server lifetime (in seconds) | `180` | 📌 The PSK (Pre-Shared Key) must match the credentials registered using the [1NCE PSK API](/api/1nce-os/create-pre-shared-device-key/) > ⚠️ The PSK **must be provided in HEX format**, not plain text. 💡 **Example:**\ If your desired PSK is the string `KeyPass123`, you must convert it to its hexadecimal representation. **Conversion:** * Input string: `KeyPass123` * HEX format: `4b657950617373313233` Use this HEX value (`4b657950617373313233`) when setting `CONFIG_NCE_LWM2M_BOOTSTRAP_PSK`. ✅ Tools for conversion: * Online: [RapidTables String to Hex](https://www.rapidtables.com/convert/number/ascii-to-hex.html) * Terminal (Linux/macOS): ```bash echo -n 'KeyPass123' | xxd -p ``` *** ## 🔓 Unsecured LwM2M (Testing Only) To run without DTLS (e.g., during integration testing): ```conf CONFIG_LWM2M_DTLS_SUPPORT=n CONFIG_LWM2M_CLIENT_UTILS_SERVER="coap://lwm2m.os.1nce.com:5683" ``` *** ## 🧩 Feature Modules ### Input Controls | Module | Description | Condition | | ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------- | | `CONFIG_APP_PUSH_BUTTON` | Enable push button support (Object 3347) | All boards: • Thingy:91 (1 button) • nRF9160 DK & nRF9151 DK (2 buttons) | | `CONFIG_APP_ONOFF_SWITCH` | Enable on/off switch input support (Object 3342) | DK boards only: • nRF9160 DK (2 switches) • nRF9151 DK (Buttons 3 and 4 are used as switches) | #### Main LwM2M Resources for Push Button and On/Off Switch Objects | Resource ID | Name | Type | Description | | ----------- | ------------------------ | ------- | -------------------------------------------------------- | | `5500` | Digital Input State | Boolean | `true` if pressed/on, `false` if released/off | | `5501` | Digital Input Counter | Integer | Number of times the button/switch has toggled | | `5518` | Timestamp of Last Change | Time | Time of the last change (press/release or on/off toggle) | 💡 **Note:** * Resource values can be monitored by sending an `observe-start` request to the relevant object (e.g., `/3347`) using 1NCE OS device controller. ### Output Controls | Module | Description | Condition | | -------------------------- | ------------------------------------ | -------------- | | `CONFIG_APP_LIGHT_CONTROL` | Enable LED output (Object 3311) | All boards | | `CONFIG_APP_BUZZER` | Enable buzzer output (Object 3338) | Thingy:91 only | *** ## 🧾 Device Identity Set device manufacturer and type: ```conf CONFIG_APP_MANUFACTURER="Nordic Semiconductor ASA" CONFIG_APP_DEVICE_TYPE="OMA-LWM2M Client" ``` 💡 **Notes:** * Those values are stored in the `/3/0/0` and `/3/0/17` resources of the device object. * The device object is not included in passive reporting, but it can be retrieved by sending a `Read` request to object `/3` using 1NCE OS device controller. *** ## 🔧 Logging Configure log levels for the application: ```conf CONFIG_APP_LOG_LEVEL_INF=y CONFIG_LOG=y ``` *** # 1NCE Zephyr blueprint - 1NCE FOTA Mender Demo ## Overview The **1NCE FOTA Mender Demo** enables firmware-over-the-air (FOTA) updates through [Mender.io](https://mender.io) using the 1NCE CoAP Proxy for secure and efficient communication. The device securely connects, authenticates, checks for firmware updates, downloads new versions, and updates itself. On the `Thingy:91`, the LED colors indicate the following statuses: * ⚪ **Flashing White** – Connecting to the network * 🟢 **Solid Green** – Firmware version 1 running * 🟡 **Flashing Green / Flashing Blue** – Firmware is being downloaded * 🔵 **Solid Blue** – Firmware version 2 running #### 📟 Development Kits (nRF9160DK / nRF9151DK) While the firmware is being downloaded, the DKs show a circular LED pattern across the four LEDs: * 🔄 LEDs 1 → 2 → 3 → 4 blink in sequence, repeating until the download is complete. *** ## Mender Integration This demo requires the [1NCE Mender Plugin](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-fota-management-mender/) to be installed and enabled. You can use prebuilt binaries and artifacts for quick testing. *** ## Running the demo ### 1️⃣ Build & Flash Flash the demo to the board using VS Code or nRF Connect for Desktop: * For **Thingy:91**, use [nRF Connect Programmer](https://www.nordicsemi.com/Products/Development-tools/nRF-Connect-for-Desktop/Download). * For **nrf9151DK & nrf9160DK**, the firmware can be flashed directly from **VS Code**. > ⚠️ **Windows Path Length Warning** > > On **Windows**, long file paths may cause build errors during the demo compilation.\ > 👉 To avoid this issue, move the project folder to a shorter path such as: > > ```bash > C:\dev\fota_mender_demo > ``` ### 2️⃣ Accept the Device in Mender When starting the demo for the first time, the device will attempt to register with the Mender server. 🛡️ **Manual Approval Required:**\ You must manually **accept the device** in the [Mender Dashboard](https://hosted.mender.io/ui/) before it can receive any updates. #### 🔁 After acceptance: * The device will **periodically check** for firmware updates * Its **inventory** (such as IMEI, artifact name, and device type) will be updated in the Mender dashboard :::tip ### You can view this info under the **Devices** section after the device is authorized. :::
![Device listed in Mender dashboard after acceptance.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/501c9f2fff0543aa4368fc487586f78edcfbe90794f302c30aa1d93e7b3891f9-image.png)
### 3️⃣ Bump Version & Rebuild To simulate a firmware update: 1. Open your `prj.conf` file 2. Update the following configuration options to reflect the new version: ```conf CONFIG_APPLICATION_VERSION=2 CONFIG_ARTIFACT_NAME="release-v2" ``` 3. Rebuild the firmware using your preferred method (e.g., west build, VS Code) ### 4️⃣ Create & Upload Mender Artifact 📦 Firmware updates in Mender are distributed as **artifacts**. #### 🛠️ Create Artifact with `mender-artifact` 1. **Install** the [Mender Artifact Tool](https://docs.mender.io/downloads#mender-artifact) 2. **Run** the following command to generate a new artifact: :::note ### Replace the placeholders with your actual values. ::: ```bash mender-artifact write module-image \ -t thingy \ -o release-v2.mender \ -T release-v2 \ -n release-v2 \ -f build/nce_fota_mender_demo/zephyr/zephyr.signed.bin \ --compression none ``` 📌 Replace values as needed for your device: * `-t`: Device type (`CONFIG_MENDER_DEVICE_TYPE`) * `-n`: Artifact name (`CONFIG_ARTIFACT_NAME`) * `-T`: Payload type (e.g. release-v2) * `-f`: Firmware binary file path (usually `build/nce_fota_mender_demo/zephyr/zephyr.signed.bin`) 3. **Upload** the generated `.mender` file to the **Releases** section in the Mender dashboard.
![Upload the new artifact to the Releases section.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/d32e239300d120c8217e3fb36ecb5f3d98e8d0f99d8ccfdf11e1c6463913f301-image.png)
## 5️⃣ Deployment Creation Once your artifact is uploaded to the Mender **Releases** section, you're ready to deploy it to your device(s). 1. Navigate to the **Deployments** tab in the Mender dashboard. 2. Click **Create Deployment** and follow the wizard: * Select the **target device** or **device group**. * Choose the **artifact** you previously uploaded.
![Create a deployment in the Mender dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/fe24d9c5ab727993dd50a9f2a72ccf905ad8674e7f340f9d5dee4227501c5017-image.png)
*** #### 🚦 Deployment Status Flow After creation, the deployment will appear in the list with an initial status of `pending`.\ As your device contacts the Mender server, the status will progress automatically: ``` pending → downloading → rebooting → installing → success ✅ / failure ❌ ```
![Deployment status flow in Mender dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/d18c6b7558331c4e3116d3c41c543e88a80a1a055cb230a20473547cf39673c8-image.png)
*** ## ⚙️ Configuration Options The following configuration options are available for customizing the Mender FOTA demo: ### 🧩 General Options | Config Option | Description | Default | | ------------------------------------------------- | ------------------------------------------------ | -------------- | | `CONFIG_APPLICATION_VERSION` | Application version reported to Mender | `1` | | `CONFIG_ARTIFACT_NAME` | Mender artifact name (used in artifact creation) | `"release-v1"` | | `CONFIG_MENDER_DEVICE_TYPE` | Device type used for update compatibility | `"thingy"` | | `CONFIG_MENDER_FW_UPDATE_CHECK_FREQUENCY_SECONDS` | Firmware update check interval (in seconds) | `30` | | `CONFIG_MENDER_AUTH_CHECK_FREQUENCY_SECONDS` | Auth check interval (when unauthorized) | `30` | *** ### 🔐 Secure Communication | Config Option | Description | Default | | ----------------------------------- | ----------------------------------------------------- | -------------------------- | | `CONFIG_MENDER_URL` | Mender backend URL | `"eu.hosted.mender.io"` | | `CONFIG_NCE_MENDER_COAP_PROXY_HOST` | CoAP proxy hostname provided by 1NCE | `"coap.proxy.os.1nce.com"` | | `CONFIG_COAP_SERVER_PORT` | CoAP server port (5684 if DTLS is enabled, else 5683) | `Auto` | | `CONFIG_NCE_MENDER_COAP_URI_PATH` | URI path for proxying CoAP requests to Mender | `"mender"` | *** ### Unsecure CoAP Communication By default, the demo uses 1NCE SDK to send a CoAP GET request to 1NCE OS Device Authenticator. The response is then processed by the SDK and the credentials are used to connect to 1NCE endpoint via CoAP with DTLS. To test unsecure communication (plain CoAP), disable the device authenticator by adding the following flag to `prj.conf` ``` CONFIG_NCE_DEVICE_AUTHENTICATOR=n ``` *** ## 📦 Ready-to-Flash Firmware for Thingy:91 For quick testing, we provide **prebuilt firmware binaries** that can be flashed directly to your Thingy:91 device — no build setup required. Available prebuilt files: | Version | Binary (.bin) | HEX (.hex) | Mender Artifact (.mender) | | ------------ | ---------------- | ---------------- | ------------------------- | | `release-v1` | `release-v1.bin` | `release-v1.hex` | `release-v1.mender` | | `release-v2` | `release-v2.bin` | `release-v2.hex` | `release-v2.mender` | 👉 **Flash directly using:** [`release-v1.hex`](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_fota_mender_demo/thingy_binaries/release-v1.hex) or [`release-v2.hex`](https://github.com/1NCE-GmbH/blueprint-zephyr/blob/main/plugin_system/nce_fota_mender_demo/thingy_binaries/release-v2.hex) :::warning These builds enable all LTE bands, so the initial network registration may take several minutes while scanning. ::: *** # 1NCE Zephyr blueprint - 1NCE Memfault Demo ## Overview The **1NCE Memfault Demo** enables Zephyr-based devices to send diagnostics and fault data via **CoAP** using the **1NCE CoAP Proxy**. This is useful for tracking faults, crashes, and network issues in IoT devices. Communication can optionally be secured using **DTLS**. On the `Thingy:91` device, LED indicators show the following statuses: * 🔵 **BLUE** – Network connected * 🟢 **GREEN** – Memfault data sent successfully * 🔴 **RED** – Failed to send Memfault data *** ## 🔌 Memfault Integration To use this demo, install and enable the [Memfault Plugin](/docs/v2/1nce-os/1nce-os-plugins/1nce-os-plugins-device-observability-memfault/) for 1NCE OS. 📦 SDK Requirement: [nRF Connect SDK v2.8.0](https://docs.nordicsemi.com/bundle/ncs-2.8.0/page/nrf/gsg_guides.html) *** ## ▶️ Running the Demo ### 1️⃣ Build & Flash **Build** the project for either `thingy91/nrf9160/ns` or `nrf9160dk/nrf9160/ns` or `nrf9151dk/nrf9151/ns`. * Flash using **VS Code** for DKs or **nRF Connect Programmer** for Thingy:91. * Firmware path (Thingy:91):\ `build/nce_debug_memfault_demo/zephyr/zephyr.signed.hex` > ⚠️ On Windows, avoid long folder paths to prevent build errors. > > Use something like `C:\dev\memfault_demo` *** ### 2️⃣ Upload Symbol File to Memfault To enable metric processing: * Go to **Memfault Dashboard > Symbol Files** * Upload:\ `build/nce_debug_memfault_demo/zephyr/zephyr.elf` 📘 [Symbol File Guide](https://docs.memfault.com/docs/mcu/symbol-file-build-ids)
![Upload the ELF symbol file to Memfault.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/81f6622dca350284f5af6fb7f4e8b3571f336887884009a12741c0475a49726c-image.png)
![Memfault symbol file upload confirmation.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/41038e9dee3d836b4d387b0e3d9f3e2633c28dfc21e1f3446f4ae021ce91a307-image.png)
*** ### 3️⃣ Authorize the Device The device will register itself using the SIM’s **ICCID** as its serial number.\ You’ll see it appear in the **Devices** view of Memfault.
![Device listed in Memfault dashboard.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/2e67755f68f053bc70ee280135d0e4dd3ab774d3d6df18acb63fba7ebb7ebb8e-image.png)
*** ### 4️⃣ Generate Events On boot, two events are sent automatically: * `heartbeat`: Contains standard metrics * `reboot`: Reports cause of last reboot Use the CLI to trigger more: ```bash nce post_chunks # Push buffered data now nce divby0 # Trigger division-by-zero crash nce sw1 # Increment switch_1_toggle_count nce sw2 # Log switch_2_toggled event nce disconnect # Simulate disconnection and reconnection ``` The overview dashboard shows a summary of recent device issues:
![Memfault dashboard overview of device issues.](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/e4ed2f35b3f1d77a6ad907eceebf6906d8335afc55df7d7103e777a0e6e13326-image.png)
*** ## 🔘 Fault Injection via Buttons | Button / Switch | Description | | --------------- | --------------------------- | | Button 1 | Stack overflow | | Button 2 | Division by zero | | Switch 1 | Custom metric: toggle count | | Switch 2 | Event trace: switch toggled | 💡 On Thingy:91, use `nce` CLI instead (only Button 1 available) *** ## 📶 Connectivity Metrics Enabled by default with: ```conf CONFIG_MEMFAULT_NCS_LTE_METRICS=y CONFIG_NCE_MEMFAULT_DEMO_COAP_SYNC_METRICS=y CONFIG_NCE_MEMFAULT_DEMO_CONNECTIVITY_METRICS=y ``` ### Standard LTE Metrics * `ncs_lte_time_to_connect_ms` * `ncs_lte_connection_loss_count` * `ncs_lte_tx_kilobytes` * `ncs_lte_rx_kilobytes` ### Additional Metrics * `ncs_lte_nce_operator` * `ncs_lte_nce_bands` * `ncs_lte_nce_current_band` * `ncs_lte_nce_apn` * `ncs_lte_nce_rsrp_dbm` ### Sample Connectivity dashboard configuration:
![Sample Connectivity dashboard configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/c5697d3f72aa6ee62fbbb1dc5a82f47da0e8d8b31e628a876f9a77cc4a064925-image.png)
#### Sync Succes chart configuration:
![Sync Success chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/20e40244b6384072f88c01471319569f452abc53b64a33a32aceb4f46879fe66-image.png)
#### To create a new metrics chart:
![Create a new metrics chart](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/b7aa40b5bc2624449230752ad9d5cb07b0473d557bb0ffebc186d3ad7566619e-image.png)
#### Signal quality chart configuration:
![Signal quality chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/dcf3ed5f1393f075b296a1372bb678653afe47971dfd6e8bd7ccbc6d32c694ed-image.png)
#### Sent KB chart configuration:
![Sent KB chart configuration](/img/1nce-os/1nce-os-sdk-blueprints/sdk-blueprints-zephyr/2f7342db1ee3c9efc9fbdcddec5046201e55e133be5929c2891efa01ab160159-image.png)
*** ## 🔐 DTLS Configuration To enable secure communication: ```conf CONFIG_NCE_MEMFAULT_DEMO_ENABLE_DTLS=y CONFIG_NCE_SDK_ENABLE_DTLS=y CONFIG_NCE_DEVICE_AUTHENTICATOR=y CONFIG_NCE_SDK_DTLS_SECURITY_TAG= ``` * If onboarding is required, set `` to an empty tag and the demo will authenticate via 1NCE automatically. * On failure (3x), re-onboarding is triggered automatically. *** ## ⚙️ Configuration Options ### General Options | Config Option | Description | Default | | ------------------------------------------------------------ | --------------------------------------------------------------------------- | ------- | | `CONFIG_NCE_MEMFAULT_DEMO_PERIODIC_UPDATE` | Enable periodic Memfault updates | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_PERIODIC_UPDATE_FREQUENCY_SECONDS` | Interval between updates (seconds) | `30` | | `MEMFAULT_METRICS_HEARTBEAT_INTERVAL_SECS` | Heartbeat interval (in header file) in `config/memfault_platform_config.h` | `30` | | `CONFIG_NCE_MEMFAULT_DEMO_CONNECTIVITY_METRICS` | Collect Additional connectivity metrics | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_COAP_SYNC_METRICS` | Tracks successful/failed syncs | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_PRINT_HEARTBEAT_METRICS` | Print heartbeat metrics to serial log | `y` | | `CONFIG_NCE_MEMFAULT_DEMO_DISCONNECT_DURATION_SECONDS` | Simulated disconnect duration | `20` | | `CONFIG_NCE_MEMFAULT_DEMO_ENABLE_DTLS` | Enable secure CoAP over DTLS | `n` | *** ## 🆘 Need Help? Open an issue on GitHub for: * ❗ Bug reports * 🚀 Feature requests * 📝 Documentation issues * ❓ General questions 👉 [Create a new issue](https://github.com/1NCE-GmbH/blueprint-zephyr/issues/new/choose) *** Made with 💙 by the 1NCE Team. --- # Services Overview Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-services-overview/
![](/img/1nce-os/1nce-os-services-overview/1nce-os-architecture.png)
# 1NCE OS Overview 1NCE OS offers different services to support connecting IoT-Devices within our network. The new service is offered on both sides, integration of devices and integration of cloud services or custom webhooks. ## Device Authenticator Authenticate IoT devices against external cloud systems based on the identity of the used IoT SIM. An IoT SIM in any form factor is placed into the IoT device and acts as authenticating element by relying on the same network authentication mechanisms as 1NCE Connect. It replaces provisioning processes which include secret flashing during manufacturing and creation of secure device twins in external cloud services. [Device Authenticator](/docs/v2/1nce-os/1nce-os-device-authenticator/) ## IoT Integrator The IoT Integrator includes the Device Integrator and the Cloud Integrator. ### Device Integrator The device integrator supports to connect devices to 1NCE managed services. For that three different protocols, UDP, CoAP and LwM2M are offered. [Device Integrator](/docs/v2/1nce-os/1nce-os-device-integrator/) ### Cloud Integrator The Cloud Integrator allows to create, manage and use 1NCE webhooks and direct AWS Integrations. This provides the possibility for a customer to forward data from their devices to customer-defined HTTPS endpoints or an AWS Account with real-time information. [Cloud Integrator](/docs/v2/1nce-os/1nce-os-cloud-integrator/) ### Device Controller The Device Controller supports sending messages to the device via the 1NCE OS managed services. For that we offer three protocols in Device Integrator. [Device Controller](/docs/v2/1nce-os/1nce-os-device-controller/) ## Device Inspector The Device Inspector combines an interface for analytic, monitoring and controlling tasks for IoT devices. [Device Inspector](/docs/v2/1nce-os/1nce-os-device-inspector/) ## Device Locator With this service, the location tracking of devices and the possibility of defining geofences for devices can be controlled. [Device Locator](/docs/v2/1nce-os/1nce-os-device-locator/) ## Plugin System Plugins extend the capabilities of the 1NCE platform with services provided by 3rd party vendors. You can enable additional functionality by installing a plugin. ## Energy Saver 1NCE offers the energy saver to translate messages coming from IoT devices. Using this feature, the messages send from the devices can be shortened, which in the end is saving energy. In the frontend, an overview on how much energy is saved is provided. [Energy Saver](/docs/v2/1nce-os/1nce-os-energy-saver/) ## Admin Logs The 1NCE Admin Logs provides an intermediate storage of messages from devices. From the Admin Logs, the messages can be viewed via the Web Interface or queried using the Management API for further processing. [Admin Logs](/docs/v2/1nce-os/1nce-os-admin-logs/) --- # Data Processing Agreement Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-services-overview/1nce-os-data-processing-agreement/ ## Data Processing Agreement The Data Processing Agreement PDF can be found here: [https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf](https://1nce.com/wp-content/1NCE-data-processing-agreement-EN.pdf) --- # Terms of Use Source: https://help.1nce.com/docs/v2/1nce-os/1nce-os-services-overview/1nce-os-terms-of-use/ ## Terms of Use The Terms of Use PDF can be found here: [https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf](https://1nce.com/wp-content/1NCE-OS-terms-of-use-EN.pdf) --- # Account & Orders Source: https://help.1nce.com/docs/v2/1nce-portal/portal-accounts-orders/ # Account The "Account" tab allows the customer to view and edit their personal/company data, billing and shipping addresses as well as to manage the Auto-Top-Up payment. > ❗️ Non-Changeable Data Fields > > Due to legal reasons we cannot allow to change the company name or billing country of the billing address. For assistance please contact our support. In the Customer and User Data dropdown, the contact information and account details for the root organization and for the logged-in user can be viewed and changed. Note that the e-mail address shown in the Customer Data column is the main contact where all invoices are being sent to digitally. An additional e-mail address can be stored which receives the invoices in copy, for example the accounting department. Please select the category "Invoice" for that.\ Furthermore the category "Volume Notifications" can be selected. This includes all e-mails on volume notifications for data/SMS as well as reaching the monthly set volume limit.\ The language selection defines the contact language meaning e-mails, invoices and service notifications. In the User Data column information regarding the currently logged-in user data can be viewed and changed. The logged-in user (no matter which role) can change their personal details like name and e-mail address as well as password. These details can also be changed by an Admin or Owner via the "Users" tab except the password for the roles Owner, Admin and User. The Billing and Shipping Addresses dropdown shows all saved billing and shipping addresses. Existing entries can be changed and new addresses can be added by the customer for future orders. The addresses are stored and will appear each time the user orders additional SIM cards or Top-Ups. The Payment Details Auto-Top-Up dropdown allows to save/delete credit card details if the customer wishes to activate Auto-Top-Up for single or all SIMs. The Auto-Top-Up feature can be enabled for particular SIMs in the "My SIMs" tab or for all SIMs in the "Configuration" tab. An API call is also available.
![220422_Account_tab.PNG](/img/1nce-portal/portal-account-tab_v2.png)
*** # Orders In the "Orders" tab, all orders from the organization's 1NCE account are listed. The table provides an overview of the important order parameters as well as the current status of an order. The status indicator (completed, in preparation or cancelled) can be used to monitor pending orders.\ On this page, previous invoices of specific orders can be downloaded. Additionally, a CSV list of all SIMs of a particular order can be downloaded using the link in the "Affected SIMs" column. This list for a dedicated order consists of ICCID, label, IMSI and MSISDN of the SIMs. In case there has been any correction to the order, the corrected or updated invoices can be downloaded in the column "Additional Documents".
![orders_v2.png](/img/1nce-portal/order_v2.png)
--- # Configuration Source: https://help.1nce.com/docs/v2/1nce-portal/portal-configuration/ ## Network Settings The network settings contain the basic information to get the SIM Cards connected to the 1NCE network. | Parameter | | | :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `1NCE APN` | Needs to be set in the very first step to set up a connection to the network. | | `SMSC Number` | Is generally needed to aim all Mobile Originated SMS in the network, although this setting is rarely needed for manual configuration. | | `Internet Breakout` | Shows the IP addresses used for all 1NCE SIMs to access the public internet through a NAT. Get all available [Internet Breakout IPs](/docs/network-services/network-services-internet-breakout) | | `IP Address Space` | Shows the IP spaces assigned to SIMs in the given organization. Each SIM has a static IP address which can to be used for direct access via the VPN Service. Additional IP spaces will be assigned for new SIM orders if the remaining IP space is not large enough. | | `IP Addresses` | Shows the availability of the IP address spaces assigned to the organization. |
![Network Settings in the Configuration tab.](/img/1nce-portal/portal-configuration_v2.png)

Network Settings in the Configuration tab.

*** ## Monthly Limits By using "Monthly Limits" a customer can set an individual monthly data and SMS limit. The SMS limit can be configured separately for Mobile Originated (MO) and Mobile Terminated (MT) SMS. These limits will be applied to all of the customer's SIMs. By checking or unchecking the boxes these options can be set or cancelled easily at any time. The limits apply to the period of the calendar month. Putting another limit in the same month will not reset the previously consumed quota. Example: The first limit is 100 MB. After reaching it you put in 200 MB as a new limit. Now only 100 additional MB can be consumed because the previously consumed 100 MB are considered. ### Exceeding the Limits When the self-set limits are exceeded, error or warning messages are triggered based on the type of limit. #### Data Session When the limit is reached, new PDP data sessions will be rejected: **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** However, some devices might retry indefinitely to reconnect in such a case. 1NCE strongly advices to use a back-off approach in this rejection case to not flood the network with PDP session requests. #### MT-SMS Using the 1NCE API, if the self-set limit for MT-SMS is reached, **Traffic limit of X SMS per month exceeded** is returned as error. In the 1NCE Portal **Set monthly limit of SMS exceeded** is shown, when the MT-SMS limit was reached and a new SMS is issued. #### MO-SMS For **MO-SMS** no notification will be shown in the 1NCE Portal or Data Stream. The SMS will be rejected by the network resulting in an error return code from the device modem.
![Monthly Limits configuration for Data and MO-/MT-SMS.](/img/1nce-portal/portal-configuration-vpn_v2.png)

Monthly Limits configuration for Data and MO-/MT-SMS.

*** ## Global IMEI Lock A global IMEI Lock can be set for all SIM Cards of the organization. The IMEI lock works by saving the IMEI of the device the SIM is installed in. With the feature enabled, the 1NCE network will only accept the saved device IMEI - SIM card combination to access the network resource. Any other IMEI - SIM combination will be refused. If this feature is activated, the IMEI lock will be set during the next network attach. Consequently the SIM card can only be used with the current device. For new SIM Card orders a checkbox can be selected to enable the IMEI lock by default. This way newly ordered SIMs will have the IMEI Lock set automatically. A separate IMEI lock for individual cards of the organization can be set either via the 1NCE API or in the "My SIMs" tab.
![Global IMEI SIM lock settings.](/img/1nce-portal/portal-configuration-breakout_v2.png)

Global IMEI SIM lock settings.

*** ## Auto Top-Up Automatic Top-Ups can be configured globally for all SIMs of an organization. The top-up will be automatically booked once a SIM card has \<20 % data and/or SMS volume. The check for low volume and potential Top-Up process if the SIM volume is less than 20%, are performed every four hours at 0:00, 4:00, 8:00, 12:00, 16:00, and 20:00 CET. To use this feature customers have to add their credit card details in the "Account" tab. By ticking the check-box it is possible to activate the auto-top-up for all future SIM orders by default. This feature can also be individually (de-)activated for a single SIM card via the Management API or the tab "My SIMs" and then the SIM-Detail page.
![Auto Top-Up configuration for enabling global SIM top up.](/img/1nce-portal/portal-configuration-dns_v2.png)

Auto Top-Up configuration for enabling global SIM top up.

*** ## Data Streams The 1NCE Data Streaming Service allows customers to subscribe to real-time events and usage data for all SIM Cards by pushing data directly to the customer's server or an already integrated cloud service such as AWS Kinesis, S3, DataDog or Keen.io. The Data Streams configuration shows a list of all currently configured streams including the name, API type, stream type, URL, status indicator and controls for each stream. Each stream can be controlled individually. Besides basic stop, start and delete, a stream integration can be restarted. A restart needs to be performed if the stream enters a error state and needs to be recovered. To create a new data stream integration click on the New Data Stream button. Further details on how to setup a stream integration can be found in the [Data Streamer Setup Guides](/docs/platform-services/platform-services-data-streamer/data-streamer-setup-guides/) section of the Developer Hub.
![Overview of the current Data Streamer integrations.](/img/1nce-portal/portal-configuration-sms_v2.png)

Overview of the current Data Streamer integrations.

*** ## OpenVPN Configuration OpenVPN is the recommended application setup by 1NCE to establish a secure, bidirectional data connection between the 1NCE network and the customer server.
![Specific configuration for Manual Mode (Europe) breakout.](/img/1nce-portal/portal-configuration-ip_v2.png)

Specific configuration for Manual Mode (Europe) breakout.

The OpenVPN client needs to be installed on the customer server to which the SIMs should access via the VPN client IP. For the OpenVPN connection to the 1NCE network a configuration file and credentials file is needed. These files can be downloaded in this section of the 1NCE Customer Portal. There are two different versions for Windows and for Linux/MacOS available. For more details about the VPN Service, its setup and operation users can proceed to the [VPN Service](/docs/network-services/network-services-vpn-service/) section of the Developer Hub. --- # Dashboard Source: https://help.1nce.com/docs/v2/1nce-portal/portal-dashboard/ After logging into to the 1NCE Customer Portal, an overview Dashboard is presented. The page shows the current SIM status, volume usage and a current order overview from the organization. ![1NCE_Portal_Dashboard.png](/img/1nce-portal/dashboard_v2.png) *** # SIM Status The "SIM Status" tile shows the current percentage of 1NCE SIMs that are activated and deactivated. SIMs can be (de-)activated by the customer to disable/enable the SIM specific connectivity. This process can be done via the 1NCE Portal or the 1NCE API. *** # Data Volume & Usage Regarding the data volume and usage, two tiles are presented in the dashboard. Details about the SIM specific quota and usage can be viewed in the "My SIMs" tab. The "Data Volume" tile shows the amount of SIMs with sufficient volume (greater 20%), low volume (less than 20%), and no volume. SIM Cards with sufficient or low volume still operate as expected, but an eye should be kept on SIMs with low volume. SIMs with the status "No Volume" have exceeded the purchased volume and have been blocked from accessing the data connection. These SIMs need to be topped up to receive new data volume credits. They can still connect to the network and send/receive SMS if sufficient SMS volume is present. The overall data usage of the organization is shown in the "Data Usage" plot. This plot shows the accumulated weekly volume in megabytes used over the last eight weeks. For more detailed usage records, the 1NCE API or 1NCE Data Streamer integration can be used. *** # SMS Volume & Usage Similar to the data volume and usage, two tiles for the SMS volume and usage are presented in the dashboard. Details for specific SIMs can be accessed via the "My SIMs" page. The SMS volume tile shows the amount of SIMs with sufficient volume (more than 20%), low volume (less than 20%), and no volume. Once a SIM has no SMS volume left, the data services can still be used but no further SMS can be sent or received. The SIM needs to be topped up to receive new SMS credits. The SMS usage is shown in a plot accumulated weekly for the last eight weeks. For more detailed usage records, the 1NCE API or 1NCE Data Streamer integration can be used. *** # Latest Orders In the "Latest Orders" tile, the past five orders with date and order ID references are shown in a quick access table. More information about the last orders can be accessed via the "Details" button. A new order can be directly triggered with the "Reorder" button. --- # Performance & Support Source: https://help.1nce.com/docs/v2/1nce-portal/portal-performance-support/ # Performance The performance dashboard provides an insight into the key components and their current status of the 1NCE Services. In case of any incident, the status of the particular service will change accordingly. Customers can use this page to get a better understanding of a current incident and receive updates. Below the overview, a list of recent incidents in the network with a detailed description is listed.
![The 1NCE Performance dashboard, showing the current status of all 1NCE Services.](/img/1nce-portal/performance_v2.png)
*** # Support Through the "Support" tab, 1NCE customers can quickly access documentation resources as well as technical support and customer service. On the page, links to the 1NCE Developer Hub, API Reference and a search integration for the documentation is given.
![Support DevHub.PNG](/img/1nce-portal/support_v2.png)
Technical support and customer service is provided either directly via phone or by placing a new service request ticket. The access to technical support is only available for existing customers. Customer service is provided either in German or English language. Telephone support is available from Monday to Friday from 9 a.m. to 6 p.m. (CET/CEST) (except for national public holidays). Tickets are mainly processed within the service hours. --- # My SIMs & SMS Console Source: https://help.1nce.com/docs/v2/1nce-portal/portal-sims-sms/ The "My SIMs" tab provides an overview of all SIMs currently attached to the specific organization. This page is used as an overview and to configure all SIM functionalities from the 1NCE Portal.
![20220214_SIM List.PNG](/img/1nce-portal/portal-sim-list_v2.png)
*Overview of the My SIMs page, showing all SIMs of the organization.* *** # SIM Overview The view of all SIMs can be customized by altering the filter options or by using the search function to filter for specific parameters. The search option allows the user to search for a certain SIM by IMSI, Label, ICCID or MSISDN. The search supports a partial search as well. Basic global filtering for data and SMS volume and SIM card status can be applied. The values in the columns can be sorted in an ascending or descending order. By default the table is sorted by ICCID. The table can be sorted and filtered via the column titles. When a column is sorted or filtered an icon becomes visible. Further, the shown columns can be (de-)activated to select only the ones of interest using the "Adjust Columns" feature. Note, that for large number of SIM Cards there can be multiple pages of the list view. The number of SIMs per page can be set manually and has a maximum number of 500. Below, an explanation of all available columns to select from: ## Status | Parameter | Description | | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Activated` | Green checkmark, indicating that full SIM functionality is activated and the SIM can connect to the 1NCE services. | | `Deactivated` | Black cross, indicating that the SIM is deactivated. The SIM cannot connect to the 1NCE network. | | `Expired` | The `Expired` status indicates that the SIM card has reached the end of its lifetime and is no longer active. This means the SIM is fully suspended in the network and cannot connect anymore. Using a Lifetime Extension can reactivate the SIM. | ## Session | Parameter | Description | | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Online` | Green Light: The SIM has established a data session. When a SIM device does not properly close the PDP data session, this status will remain until the device is flushed from the network. | | `Offline` | Red Light: The SIM device is not connected to the 1NCE network. | | `Attached` | Amber Light: The SIM is attached to a mobile network, but has no active data session. When a SIM is not properly detached from a network, this status will remain until the device is flushed from the network. | ## SIM Details | Parameter | Description | | --- | --- | | `ICCID` | Unique serial of the SIM card. | | `MSISDN` | Phone number of the SIM card. The SIM can not be used for voice services or to receive/send SMS to external parties. The chapters [SMS Services](/docs/connectivity-services/connectivity-services-sms-services) and [SMS Forwarding Service](/docs/platform-services/platform-services-sms-forwarder) provide more information. | | `IMEI(SV)` | Identifier of the device the SIM is inserted into. The IMEI displayed in the 1NCE Portal is retrieved from the network during PDP context activation, the format is as follows: IMEI + SV (software version), based on the standard specification 3GPP TS23.003. See the IMEI Reference for more information. | | `IMEI Lock` | Status of the IMEI lock for this specific SIM. If enabled the SIM is bound to the current device. See the IMEI Lock Reference for more information. | | `IP Address` | Static IP address of the specific SIM. Used for accessing the SIM via 1NCE VPN Services. | | `SIM Type` | Specific type of SIM card, FlexSIM or eSIM. | | `Tariff` | Details about the tariff of the specific SIM showing the data and SMS volume. | | `Label` | Self-set label text for the specific SIM card. | | `Auto-Top-Up` | Indicator if Auto-Top-Up is enabled for this SIM. | | `Data Usage` | Colored indicator of the remaining data quota. Green > 20% remaining, Yellow \< 20% available, Red = 0 % remaining. | | `SMS Usage` | Colored indicator of the remaining SMS quota. Green > 20% remaining, Yellow \< 20% available, Red = 0 % remaining. | ## SIM Export The complete and customized SIM Card table can be exported as a CSV-file if needed by using the "Export SIMs" button. As it might take some time to export a larger list of SIMs, the user gets an e-mail notification as soon as the export is completed and can be downloaded from the SIM Export section underneath the SIM card table. This export also includes the PIN and PUK of each SIM which might be needed for certain devices.
![20220214_Downloads.PNG](/img/1nce-portal/portal-downloads_v2.png)
*SIM Export section below the SIM table* *** # SIM Management Each SIM card in the list view can be selected using the checkbox on the left side of each list entry. By selecting one or several SIMs the user can perform different actions like (de-)activating SIMs, setting the IMEI lock, configuring Auto-Top-Ups or manually recharging the SIM data and SMS volume. These actions can be triggered for the selected SIMs using the buttons in the action bar appearing once SIMs are selected. Additional SIMs can be ordered from here as well with the "Reorder" button on the top right of the table.
![20220214_Action bar.PNG](/img/1nce-portal/portal-action-bar_v2.png)
*Selected SIMs with open action bar* ## SIM Top-Up It is possible to manually book additional data and SMS volume for one or more selected SIM cards. With every Top-Up 500 MB and 250 SMS are added to the remaining volume. Top-Ups for single SIM cards can be booked in the detailed view of a card. More volume can be added by ordering multiple Top-Ups in a row. The booked volume is available as soon as the payment is received: | Payment method | Duration | | :------------- | :---------------- | | Bank transfer | Two to three days | | Credit card | Immediately | For automatically booked volume, please refer to our [Auto-Top-Up-feature](/docs/1nce-portal/portal-configuration#auto-top-up). ## SIM Deactivation The selected SIM can be deactivated to prevent an attachment to the 1NCE network. This feature is useful for disabling SIMs during shipping of devices or to force a reset of the connection. This function can also be used through the 1NCE API. Active attachments of SIMs will be purged and devices immediately disconnected. Subsequent attempts of the device to re-register will be refused by the network until the SIM is re-activated. Depended on the device logic this blocking might force some devices to get into an error state and prevent them from reconnecting to any network even if the SIM has been re-activated again. Implementing a soft- or hard-restart with an **exponential back-off** timer as part of the connectivity procedure of the device firmware is advised. This procedure should circumvent the potential delay in attaching after a SIM reactivation where the device was stuck in an error state. Please implement a back-off algorithm with at least 5-20 minutes between reattempts to not overload the network with undesired attach requests during SIM deactivations. After reactivating the SIMs, the network will once again allow the SIM to attach to the 1NCE network and use all services as usual. ## IMEI Lock The IMEI lock will only be set for the selected SIMs. It works by saving the IMEI of the device the SIM is installed in. With the feature enabled, the 1NCE network will only accept the saved device IMEI - SIM card combination to access the network resource. Any other IMEI - SIM combination will be refused. If this feature is activated, the IMEI lock will be set during the next network attach. As a consequence, the SIM card can only be used with the current device. To change the setting for all (future) SIM cards please navigate to the tab [Configuration](/docs/1nce-portal/portal-configuration#global-imei-lock). ## Auto-Top-Up Automatic Top-Ups can be configured for all selected SIMs. The Top-Up will be automatically booked once a SIM card has \<20 % data and/or SMS volume. The check for low volume and potential Top-Up process if the SIM volume is less than 20%, are performed every four hours at 0:00, 4:00, 8:00, 12:00, 16:00, and 20:00 CET. To use this feature the customer has to add their credit card details to the account via the "Account" tab. To activate this for all (future) SIM cards please navigate to the tab [Configuration](/docs/1nce-portal/portal-configuration#auto-top-up). By ticking the check-box it is possible to activate the Auto-Top-Up for all future SIM orders by default. ## SIM Extension If your SIM cards are close to expiring, you will see an extra column in your SIM table called "Extendable". Three months before the end of your activation period you will be notified by e-mail and it will be visible in your SIM table which SIM cards can be extended. You can extend a single SIM card or filter for all extendable SIM cards. After selecting all relevant SIM cards, click on "Extend SIMs". You will be able to review your selected SIMs and the tariff details for the extension in the shopping cart. All of remaining data, SMS, and time will be transferred. The new activation period starts on the order day (when bank transfer is used, it starts as soon as the payment is received. After your expiry date has been reached you have 18 months to extend your SIM cards. The SIMs will not be usable in that transition period but you can extend them anytime. After 18 months the SIM cards will be irreversibly deleted.
![220824_SIM List_Extensionpng.png](/img/1nce-portal/portal-sims-sms/687f26f-220824_SIM_List_Extensionpng.png)
*SIM Extension* *** # SIM Detail Page By clicking on one of the SIMs in the list, a detailed view of the SIM status and configuration is shown. The top section of this view includes basics stats of the selected SIM. In the first column, the ICCID, IMSI, MSISDN and LABEL is shown. The LABEL field is editable and can help to assort the SIMs. The second column presents all lifetime data like time passed in %, the time left and the end date of the contract. The third column on the right shows all relevant network data, like the static IP-address, the IMEI of the connected device, the session-status, location of the device, the operator and the network bearer the SIM currently is attached to. ## SIM Configuration On the SIM detail page, the specific SIM can be (de-)activated, the IMEI lock set, Auto-Top-Up (de-)activated and additionally the SIM connection can be reset.
![1NCE_SIM_Details.PNG](/img/1nce-portal/portal-sim-details_v2.png)
*Detail page of an example SIM Card.* ## Reset Connection By using "Reset Connection", the SIM is automatically deactivated and afterwards reactivated. This will force the SIM to disconnect from the current network operator and reattach. This feature is useful if the SIM is stuck in an unwanted connection. In the lower section, detailed logs of events and usage in chronological order are presented. Please note that this data is only retained for seven days due to the 1NCE data retention policy. The data in the Events tab is identical to the data found in the 1NCE Data Streamer. These events are very useful for debugging devices and seeing the current network events of a device. The Usage tab shows both the SMS and data usage of the last eight weeks, the available quota and the remaining volume for SMS and Data of this particular SIM. *** # SMS Console The SMS tab of the detailed SIM page can be used to exchange SMS messages with the device using the particular SIM. With the Source Address and Payload fields, a SMS can be prepared and send to the device. Please note that the device needs to be attached to a network in order to receive the message. In the table view below the sent SMS form, an overview of the Mobile Originated (MO) and Mobile Terminated (MT) SMS messages of the last seven days can be seen. To properly receive and process MT messages, review the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) guide. Besides the messages itself, the current status of the MO-/MT-SMS, the payload and type is listed. The list shows the type of SMS (MT or MO), the current status (Pending, OK, Failed), the timestamp the message was submitted and finally, the source address and the actual payload. Please note that MT-SMS will stay in the Pending state until the device has attached to the network and the message was delivered. For MO-SMS the state will remain in "pending" if no SMS Forwarding Service is setup as only this service will consume the SMS messages and properly acknowledge them. If a SMS message fails this is most likely due to reaching the delivery retry timeout. After a certain time of trying to deliver a message, the service will put the SMS into the failed state.
![1NCE_SMS_Console.png](/img/1nce-portal/portal-sms-console_v2.png)
*Overview of the SMS Console.* --- # Users & Organisation Source: https://help.1nce.com/docs/v2/1nce-portal/portal-users-organisations/ # User Management The 1NCE Customer Portal offers the option to create multiple user accounts which allows for different user roles and access rights. In the "User" tab a root owner of the account can create and edit new user accounts. A general overview of all current users of the 1NCE organization is provided in a list view.
![1NCE_User_List.PNG](/img/1nce-portal/portal-user-list_v2.png)
## User Roles The following roles for additional user accounts are available: | Role | Description | | --- | --- | | Owner | Initial user of the organization that cannot be changed. Includes all functionalities and access to the entire organization. New users can have the Owner role assigned as well. The Owner can generate Management API credentials under Account → Management API Access. Can administer users with the Admin, User, and Read Only roles. *To administer Owner, please submit a service request.* | | Admin | Includes all functionalities and access to the entire organization. Can administer users with the User and Read Only roles. | | User | Can manage SIM Cards in the Portal, but has no access to orders and top-ups, and cannot trigger new orders or manage users. | | Read Only | User role designed to allow Read-only access to the Portal. | ### User Roles Details See the following table for an exact overview of the roles and the permissions for each component of the 1NCE Portal.
Portal Areas Owner Admin User Read Only
Dashboard See All ✅ ✅ ✅ ✅
Reorder Button ✅ ✅ ❌ ❌
Latest Order Widget ✅ ✅ ✅ ✅
My SIMs See All ✅ ✅ ✅ ✅
SIM State ✅ ✅ ✅ ❌
IMEI Lock ✅ ✅ ✅ ❌
Auto-Top-Up ✅ ✅ ❌ ❌
Reset Connectivity ✅ ✅ ✅ ❌
SIM List Export ✅ ✅ ✅ ❌
Reorder / Top-Up ✅ ✅ ❌ ❌
Send SMS ✅ ✅ ✅ ❌
Configuration Network Settings ✅ ✅ ✅ ❌
Breakout Settings ✅ ✅ ❌ ❌
Monthly Limit ✅ ✅ ✅ ❌
IMEI Lock ✅ ✅ ✅ ❌
Auto-Top-Up ✅ ✅ ❌ ❌
Data Streams ✅ ✅ ❌ ❌
SMS Forwarder ✅ ✅ ✅ ❌
OpenVPN ✅ ✅ ✅ ❌
1NCE OS Tab Available ✅ ✅ ✅ ✅
Account See All ✅ ✅ ✅ ✅
Customer Data ✅ ✅ ❌ ❌
User Data ✅ ✅ ✅ ✅
Add New E-Mail ✅ ✅ ❌ ❌
Billing and Shipping Address ✅ ✅ ❌ ❌
Payment Details ✅ ✅ ❌ ❌
Management API Access (generate credentials) ✅ ❌ ❌ ❌
Orders See All ✅ ✅ ✅ ✅
Download Invoices ✅ ✅ ✅ ✅
Trigger New Order ✅ ✅ ❌ ❌
Download Affected SIMs ✅ ✅ ✅ ✅
Users See All ✅ ✅ ✅ ✅
Administer Own User ✅ ✅ ✅ ✅
Administer Owner ❌ ❌ ❌ ❌
Administer Admin ✅ ❌ ❌ ❌
Administer User ✅ ✅ ❌ ❌
Administer Read Only ✅ ✅ ❌ ❌
Organisation See All ✅ ✅ ✅ ✅
Add Organisation ✅ ✅ ❌ ❌
SIM Transfer ✅ ✅ ❌ ❌
Performance See All ✅ ✅ ✅ ✅
Support See All ✅ ✅ ✅ ✅
New Service Request ✅ ✅ ✅ ❌
## User Creation A new user can be created using the "New User" button on the top right. The mandatory details depend on the type of the user that needs to be created. The e-mail address is used for the confirmation of the account as well as the login name for the 1NCE services. Customers have to make sure that the entered e-mail address is valid and can receive messages. After creating a new user an e-mail is sent to the new mail address requesting to set an initial new password for the 1NCE Customer Portal.
![1NCE_Add_User.png](/img/1nce-portal/portal-add-user_v2.png)
## User Account Alteration By clicking on a user shown in the list of current users, the details of this account can be changed or deleted. Changes can be applied by editing the boxes in the form and saving the new data. A user can be deleted by clicking on the "Delete" button in the Edit User popup.
![1NCE_User_Edit.png](/img/1nce-portal/portal-user-edit_v2.png)
--- # Data Streamer Service Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/ The 1NCE Data Streamer offers multiple integration possibilities. For each of the available integrations 1NCE provides a setup guide and examples for testing. Please click on one of the icons to get to the setup guide for the selected integration.
![](/img/blueprints-examples/examples-data-streamer/d47972b-rest_api.svg)
--- # DataDog Integration Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/001.png)
DataDog is a cloud monitoring service that can be used to monitor the endpoint volume (Usage records) of the 1NCE SIM cards using custom dashboards and trigger events. The following metrics can be viewed in DataDog: endpoint.volume, endpoint.volume\_tx, endpoint.volume\_rx, and endpoint.cost. *** # DataDog Data Streamer Setup For the DataDog Data Streamer configuration, a account with a new API Key needs to be setup. Afterwards, the Data Streamer integration in the 1NCE Portal can be setup. The incoming usage records can be seen on the DataDog Metrics Explorer. Follow these steps to obtain the needed parameters for the 1NCE Portal configuration. > 📘 DataDog Regions > > Please note that only the DataDog Account Regions US, US3, EU, US1FED are available for the 1NCE Data Streamer integration. 1. Setup a **DataDog Account** in one of the supported regions. 2. Go to the **Organization Settings** on the main screen by clicking on the **User Profile**. 3. Select **API Keys** from the settings menu. 4. Click **New Key** in the top right to create a new API Key.
![DataDog_Configuration_01.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/b1e2c9f-DataDog_Configuration_01.png)
5. Provide a **Name** for the API Key. 6. Click **Generate Key** to issue a new API Key.
![DataDog_Configuration_02.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/392dfc2-DataDog_Configuration_02.png)
7. The next window will show the **Key ID** and the **API Key**. 8. The Key ID is a unique identifier for the API Key and should not be confused with the actual (API) Key. 9. Click **Copy Key** to copy the API Key.
![DataDog_Configuration_03.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/e5f5329-DataDog_Configuration_03.png)
10. On the overview page, all API Keys are listed. By clicking on a Key, details of the specific API Key are shown. 11. From there the API Key can be copied or revoked.
![DataDog_Configuration_04.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/1f3d255-DataDog_Configuration_04.png)
12. Copy & Paste the **API Key** to the configuration in the 1NCE Portal. 13. Once setup in the 1NCE Portal, the Usage records of all 1NCE SIMs of the used organization will be provided to DataDog. 14. Go to **Metrics > Summary** of the DataDog project to see the available streams. Please note, SIMs need to generate some recent usage events to make the DataDog integration appear for the first time.
![DataDog_Configuration_05.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/85f1650-DataDog_Configuration_05.png)
*** # 1NCE Portal DataDog Configuration For setting up a DataDog Data Streamer integration in the 1NCE Portal, the DataDog API Key and the Region of the used DataDog Account is needed. As Stream Type only Usage Data should be used as Event records are not supported by DataDog. * **API Type:** Select DataDog to customize the settings. * **Stream Type:** Choose *Usage Data* records as Events are not supported in DataDog. * **Name:** Identification name used in the Connectivity Management Platform for labeling the specific integration. * **API Key:** The API Key created in the DataDog settings. * **Region:** Region of the DataDog Account. * Click **Save** to create the Data Streamer integration.
![datadog_integration_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/a6cdbb1-datadog_integration_cmp.png)
*** # DataDog Streamer Testing For testing a DataDog integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Usage records. Please note that DataDog only supports Usage Records. Therefore, the Data Service has to be used to generate some usage. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the Usage records the following procedures can be executed: * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data volume has been actively used. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. ## DataDog Results The incoming events in DataDog can be viewed in the Metrics Summary. All Usage Records of the 1NCE SIMs in the organization account will be forwarded to DataDog.
![DataDog_Configuration_05.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-datadog/4537f00-DataDog_Configuration_05.png)
--- # HTTP/Webhook Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/examples-data-streamer-http/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-http/001.png)
The HTTP/Webhook integration of the Data Streamer is ideal for custom server applications. This method offers the most flexible, custom integration of the Data Streamer Service into existing analytics, reporting, and monitoring pipelines. The Http callbacks supports both Event and Usage Records. # General HTTP Interface The HTTP endpoints needs to handle Posts requests with a Body containing a list of JSON objects. A maximum of 3.000 JSON object records per sent HTTP Post request can be expected. If data is available, the requests are sent in a regular interval. The customer supplied endpoint should consume the HTTP Post with a HTTP 200 status code response. Acknowledged records will not be resend again. The streamer service does not respond to HTTP redirect codes (3xx). A HTTP Basic Authentication Header must be configured in the 1NCE Portal for this Data Streamer type. ## Endpoint URL The provided endpoint URL in the 1NCE Portal Configuration needs to be valid. URLs with public IP addresses (`https://://`) are not supported. Custom ports for the endpoint can be configured via the URL (`https://://`). ## Certificate The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using [Let's Encrypt](https://letsencrypt.org/de/) certificates. ## Endpoint Capacity Be aware that the HTTP/Webhook integration will deliver the incoming events as a list of JSON objects. Dependent on the amount of SIMs and occurred records this request can be quite large. A maximum limit of 3.000 records per request is set. 1NCE customers with a large quantity of SIMs and high number of events as such must be aware that their backend system receiving data from the stream needs to have the capacity to handle large incoming requests. *** # 1NCE Portal Configuration After implementing a HTTP Post endpoint on a custom backend, the Data Streamer needs to be configured in the 1NCE Portal in the Configuration tab. For a complete Data Stream setup using HTTP/Webhook, two configurations (Events and Usage) need to be created in the 1NCE Portal. Still, the same endpoint could be used as target for both stream setups. After the configuration the SIM Event and Usage Records will be forwarded to the specified customer endpoint. 1. **API Type:** Select RestAPI to customize the settings. 2. **Stream Type:** Choose between Usage Data and Event Data records. If both record types are desired, two separate Data Streams with the same destination endpoint can be setup. 3. **Name:** Identification name used in the Connectivity Management Platform for labeling the specific integration. 4. **API Callback:** URL to the customer provided HTTPs endpoint accepting the HTTP POST requests. * The endpoint URL for the Data Streamer in the needs to be valid. * Public IP addresses (`https://"server-ip":"port"/"endpoint"/`) are not supported. * Custom ports for the endpoint can be configured via the URL (`https://"server-domain":"port"/"endpoint"/`). * The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using Let's Encrypt certificates. 5. **Basic Auth Header:** Base64 encoded value supplied by each HTTP POST request in the Basic Authentication Header field. The supplied HTTP endpoint needs to support Basic Authentication. 6. Click **Save** to create the Data Streamer integration. ![data-streamer-webhook.jpg](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-http/8a6a25f-data-streamer-webhook.jpg) *** # HTTP/Webhook Integration Testing Testing a Data Streamer integration can be done in two ways: using a 1NCE SIM in a device or sample HTTP cURL requests. This sections explains the two ways of testing the Data Streamer integration. ## 1NCE SIM Device For simple testing with a 1NCE SIM, we recommend to use a smartphone or manually controllable IoT device. 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. After the device has attached to the network, see mobile network status indicator on the smartphone, a couple of first events should show up in the Data Streamer. 4. To generate Usage Records, create a data session and use some data traffic or Alternatively send some MT/MO-SMS. Note that data session usage is only recorded after a session has been closed. For smartphone testing simply disable data roaming or airplane mode to simulate the closing of the data session. 5. Check the Usage Record integration. After some time, the used data volume and/or SMS volume record will be provided. ## Simulated Events and Usage Records To simulate HTTP/Webhook events, simple HTTP Post cURL requests with JSON List Body messages can be posted to the custom endpoints. Below two examples for an Event and Usage Record cURL can be found. Please adapt the endpoint URL to the server URL used for integration. Use Postman or Command Line Interface (CLI) to issue these example requests. The data should be received by the customer-side implemented Data Streamer receiver.
Update Location Event cURL ```curl Update Location HTTP Post cURL curl --location --request POST 'https://://' \ --header 'Content-Type: application/json' \ --data-raw '[{ "imsi": { "imsi": "", "id": 123456, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from VLR for IMSI='', now attached to VLR=''.", "alert": false, "id": 1234567890, "user": null, "detail": { "mnc": [ { "mnc": "20", "id": 327 }, { "mnc": "16", "id": 328 } ], "tapcode": [ { "tapcode": "NLDDT", "id": 470 }, { "tapcode": "NLDPN", "id": 471 } ], "name": "T-Mobile", "country": { "iso_code": "nl", "country_code": "31", "name": "Netherlands", "id": 141, "mcc": "204" }, "id": 730 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 1, "description": "Update location" }, "timestamp": "2019-01-21T09:36:17Z" }]' ```
Usage Record cURL ```curl Usage Record HTTP Post cURL curl --location --request POST 'https://://' \ --header 'Content-Type: application/json' \ --data-raw '[{ "imsi": "", "organisation": { "name": "8100xxxx", "id": 1234 }, "start_timestamp": "2021-08-09T12:59:05Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "id": 2, "name": "T-Mobile", "mnc": "01", "country": { "id": 74, "mcc": "262", "name": "Germany" } }, "tariff": { "ratezone": { "name": "Rate Zone 2 (EU - DE)", "id": 2067 }, "name": "1NCE Production 01", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "Data", "id": 5 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678, "balance": null }, "cost": 0.001176, "volume": { "total": 0.001176, "tx": 0.001176, "rx": 0.0 } }]' ```
### Postman Mock Server A good way to start with the 1NCE Data Streamer is a [Postman Mock Server](https://learning.postman.com/docs/designing-and-developing-your-api/mocking-data/setting-up-mock/). A mock server can be setup fast without any need of external infrastructure. Simply create a HTPP Post endpoint with a given name and provide the mock server URL and the chosen Endpoint name in the 1NCE Portal Data Streamer configuration. Afterwards, the Data Streamer events should be sent to the mock server. The mock server allows to inspect real network events triggered by the SIMs and organization of the customer. Further, using Postman, the CURL demo events can be sent either to the mock server or the customer server implementation. --- # Keen.io Integration Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/001.png)
The Keen.io platform is a managed event streaming platform used for streaming, analyzing, and embedding rich data. The 1NCE Data Streamer Service can easily be integrated with this service. The Keen.io integration supports both Event and Usage Records.\ These chapters guides through the initial setup of the Keen.io project, 1NCE Portal Data Streamer configuration and a guide to testing the Keen.io integration. *** # Keen.io Data Streamer Configuration For the Keen.io configuration, a account with a new project needs to be setup. Afterwards, the Data Streamer integration in the 1NCE Portal can be setup. The incoming data can be seen on the Keen.io streams tab. Follow these steps to obtain the needed parameters. 1. Set up an active Keen.io account or use an existing instance. 2. Create a new project within the Keen.io account. 3. Open the project page and go to the **Access Tab** to obtain the **Project ID** and **Write Key** from the newly created project. ![keen_access.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/9a5fec6-keen_access.png) 5. Copy & Paste the **Project ID** and **Write Key** to the configuration in the 1NCE Portal. 6. Once setup in the 1NCE Portal, the Event or Usage records of all 1NCE SIMs of the used organization will be provided as Keen.io Streams. 7. Go to the **Streams Tab** of the Keen.io project to see the available streams as a list in the Event Streams window. Please note, SIMs need to generate some recent events to make the Keen.io streams appear for the first time. This may take a while.\ 8.Once the stream integrations show up, the advanced features of Keen.io can be used to create custom Dashboards and Monitoring. ![keen_stream.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/8b017aa-keen_stream.png) *** # 1NCE Portal Keen.io Configuration After setting up a Keen.io project for the Data Streamer integration, the related parameters need to be configured in the 1NCE Portal. Please note that if both Usage and Event records should be obtained using Keen.io, 1NCE recommends to use two separate project integrations, one for each streamer type. The following parameters need to be setup in the 1NCE Portal. 1. **API Type:** Select keen.io to customize the settings. 2. **Stream Type:** Choose between *Usage Data* and *Event Data* records. If both record types are desired, two separate Data Streams with the different Keen.io projects can be setup. 3. **Name:** Identification name used in the 1NCE Portal for labeling the specific integration. 4. **Project Key:** The Keen.io Project Key from the newly created project integration. 5. **Write Key:** Write Key from the newly created Keen.io project. 6. **Collection Name:** Name of the collection created in the Kenn.io project. 7. Click **Save** to create the Data Streamer integration. ![keen_integration_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/08497b5-keen_integration_cmp.png) *** # Keen.io Data Streamer Testing For testing a Keen.io integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # Keen.io Results The incoming events in Keen.io can be viewed in the Streams Tab. Dependent on the configuration, for each received Data Streamer Event and Usage record the raw JSON data can be viewed. ![keen_stream.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-keen/2553597-keen_stream.png) --- # AWS Kinesis Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/001.png)
The 1NCE Data Streamer Service can be integrated with AWS Kinesis which is ideal for collecting and processing large streamed data records in near real-time. AWS Kinesis are integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the 1NCE Portal. The following subchapters explain the Cloud Formation and 1NCE Portal setup as well as some testing procedures. *** # AWS Kinesis Configuration To setup the 1NCE Data Streamer integration with AWS Kinesis, it is recommended to use the Cloud Formation Template provided in the 1NCE Portal. As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. After completing the steps, the selected record type should show up in the AWS Kinesis Stream bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. 1. Open the 1NCE Portal and navigate to *Configuration-Data Streams-Add New Data Stream*. 2. In the popup select AWS Kinesis as **API Type** and select the desired **Stream Type**. 3. Click on **Create IAM Role** to open the Cloud Formation Template in a separate window. ![aws_kinesis_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/049665e-aws_kinesis_cmp.png) 4. Adapt the CFN Template parameters (Stack Name, KinesisStreamName). Do NOT change AllowedExternalID and DatastreamerRoleARN. 5. Set the **IAM Creation** checkbox. 6. Execute the CFN Stack by clicking on **Create Stack**. ![aws_kinesis_cfn.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/5969b1e-aws_kinesis_cfn.png) 7. Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/1d364db-aws_cfn_done.png) 8. Go to the **Outputs** tab of the created CFN Stack. 9. Copy the shown parameters to the popup in the 1NCE Portal. 10. Click on **Save** in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_kinesis_cfn_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-kinesis/19d3af3-aws_kinesis_cfn_cmp.png) *** # Testing AWS Kinesis Data Streamer For testing a AWS Kinesis integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. After the device has attached to the network, see mobile network status indicator on the smartphone- 4. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # AWS Kinesis Results Dependent on the Data Streamer configuration the AWS Kinesis Stream will contain Event and Usage data. The data is received as JSON Objects.\ From the AWS Kinesis Stream the received data can be processed using available AWS processing tools. --- # AWS S3 Bucket Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/
![](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/001.png)
The 1NCE Data Streamer Service can be integrated with AWS S3 which is an object-based storage solution. The Data Streamer can push CSV files into a S3 bucket allowing for easy, largescale data collection and further processing later on by related AWS Services. AWS S3 is integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the 1NCE Portal. *** # S3 Filename and Data Format The S3 integration will provide the Event or Usage Records through an S3 bucket where they are uploaded as CSV files. The CSV filenames for events are "events\_YYYYMMDD\_HHmmss.csv" and "cdr\_YYYYMMDD\_HHmmss.csv" for usage records. Each file contains a collection records over a small period. A sample for an event record file type is provided below. ```text cdr_20210512_070123.csv "id","event_start_timestamp","event_stop_timestamp","organisation_id","organisation_name","endpoint_id","sim_id","iccid","imsi","operator_id","operator_name","country_id","operator_country_name","traffic_type_id","traffic_type_description","volume","volume_tx","volume_rx","cost","currency_id","currency_code","currency_symbol","ratezone_tariff_id","ratezone_tariff_name","ratezone_id","ratezone_name","endpoint_name","endpoint_ip_address","endpoint_tags","endpoint_imei","msisdn_msisdn","sim_production_date","operator_mncs","country_mcc" "4427264xxx","2021-05-11 11:17:25","2021-05-11 11:19:51","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.000741","0.000395","0.000346","0.0007410000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" "4427320xxx","2021-05-11 11:17:29","2021-05-11 11:24:56","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.003210","0.001803","0.001407","0.0032100000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" ``` *** # AWS S3 Configuration The easiest setup for the stream integration into AWS S3 is by using the Cloud Formation Template via the 1NCE Portal. As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. After completing the steps, the selected record type should show up in the AWS S3 bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. 1. Open the Portal and navigate to *Configuration-Data Streams-Add New Data Stream*. 2. In the popup select AWS S3 as **API Type** and select the desired **Stream Type**. 3. Click on **Create IAM Role** to open the Cloud Formation Template in a separate window. ![aws_s3_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/05fc0c9-aws_s3_cmp.png) 4. Adapt the CFN Template parameters (Stack Name, S3BucketName). Do NOT change AllowedExternalID and DatastreamerRoleARN. 5. Set the **IAM Creation** checkbox. 6. Execute the CFN Stack by clicking on **Create Stack**. ![aws_s3_cfn.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/a776ebd-aws_s3_cfn.png) 7. Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/90d26f6-aws_cfn_done.png) 8. Go to the **Outputs** tab of the created CFN Stack.\ 9 Copy the shown parameters to the popup in the 1NCE Portal. 9. Click on **Save** in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_s3_cfn_cmp.png](/img/blueprints-examples/examples-data-streamer/examples-data-streamer-s3/c246722-aws_s3_cfn_cmp.png) *** # Testing AWS S3 Data Streamer For testing an AWS S3 integration, an IoT or mobile network device (e.g., smartphone) with an active 1NCE SIM has to be used to generate Event and Usage records. ## Event Records 1. Place a 1NCE SIM into an IoT device or any other mobile device. 2. Ensure that the mobile device allows roaming network and data connections and that the 1NCE APN is setup correctly. 3. The attachment to a mobile network will cause a few Event records to be transmitted over the Data Streamer integration. ## Usage Records 1. Place and configure (roaming, APN, data roaming) the 1NCE SIM in a capable mobile device. 2. For testing the two Usage record types, data and SMS, the following procedures can be executed: * **SMS usage**: Send a MO-SMS from the SIM device or send a MT-SMS using the SMS Console or API to an active 1NCE SIM. * **Data usage**: Allow data roaming, configure the APN and create a data session. Smartphones will automatically create a data session. Use some data service (e.g., IMCP Ping, TCP/UDP traffic, open a website). Close the data session by deactivating the PDP session or disconnecting the device from the network. 3. Usage records are only written once the data and SMS volume has been actively used. Ensure that the SMS is finalized and delivered. For data usage, the current data session needs to be closed to get an immediate usage record in the Data Streamer. *** # AWS S3 Results Dependent on the Data Streamer configuration the S3 bucket will be filled with CSV files. These CSV files include the Event or Usage record data from the Data Stream. The CSV filenames for events are "events\_YYYYMMDD\_HHmmss.csv" and "cdr\_YYYYMMDD\_HHmmss.csv" for usage records. Each file contains a collection records over a small period. From the S3 bucket the received data can be processed using available AWS processing tools. --- # Hardware & Modem Guides Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-hardware-guides/ --- # Examples Overview Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-overview/ Often an example helps getting started with a new service integration. As addition to the documentation of the 1NCE Services in the Developer Hub, this sections provides real use case examples for these services. Find an overview of the current examples available below. We are continuously working on improving and extending the given examples. If you have feedback, questions or recommendations, feel free to reach out to us. - [Hardware & Modems](/docs/blueprints-examples/recipes/) — Modems, GPS tracker, IoT router or custom hardware getting started with 1NCE connectivity is very easy with most devices. We provide some guides to showcase common setups. - [SMS Services](/docs/blueprints-examples/examples-sms/) — Sending and receiving MO-/MT-SMS with 1NCE Connectivity, these guides show common examples to get started with SMS messaging. - [SMS Forwarder](/docs/blueprints-examples/examples-sms-forwarder/) — Setup of the SMS Forwarder using the Webhook integration. Examples for testing and debugging the Forwarder Service. - [Data Streamer](/docs/blueprints-examples/examples-data-streamer/) — From AWS to Keen.io, DataDog or Webhook integration, these setup guides for all types of Data Streamer integrations provide an easy starting point to receive, process, and analyze Event and Usage Records from 1NCE SIMs. - [VPN Integration](/docs/blueprints-examples/examples-vpn/) — Bidirectional connectivity establishment is available through the 1NCE VPN Service. We provide guides for installing the 1NCE VPN integration and instructions for basic testing, debugging and common use cases. - [More to come...]() — We are working on providing more and extended examples for getting started with 1NCE Services. --- # SMS Services Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-sms/ # Mobile Originated SMS
![](/img/blueprints-examples/examples-sms/001.png)
Mobile Originated (MO) SMS messages can be issued by devices with a 1NCE SIM card installed. As a SMS can not be send in-between different 1NCE SIM devices, all MO-SMS can only be accessed/received through the 1NCE Portal, 1NCE SMS API and the SMS Forwarder. The following sections will show examples for: * 1NCE SMS Console for MO-SMS * 1NCE API MO-SMS Integration * MO-SMS on SIM Devices Examples for the 1NCE SMS Forwarding Service can be found in the SMS Forwarder section. *** # Mobile Terminated SMS
![](/img/blueprints-examples/examples-sms/002.png)
Mobile Terminated (MT) SMS messages are destined for a device with an installed 1NCE SIM. Such MT-SMS can be issued via the 1NCE Portal using the SMS Console or using the 1NCE API. While the SMS console is great for debugging and getting started, the usage through the 1NCE API provides a fully-featured access to automate the SMS messing sending process. The following subsections will show examples for: * 1NCE SMS Console for MT-SMS * 1NCE API MT-SMS Integration * MT-SMS on SIM Devices --- # Mobile Originated SMS Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-sms/examples-mo-sms/ ## 1NCE Portal / SMS Console This section covers how to use the SMS Console inside the 1NCE Portal to view the MO-SMS messages of a specific 1NCE SIM. Please note that the data retention of seven days applies to the SMS Console, SMS older than seven days will no longer be displayed. ### Viewing MO-SMS 1. Login to the 1NCE Portal and go the the **My SIMs** tab. 2. Select the **SIM** for which the MO-SMS should be viewed from the list of all SIM cards. 3. Navigate to the **SMS Tab** at the bottom of the SIM details page to access the SMS Console.
![SMS_Console_MO.png](/img/blueprints-examples/examples-sms/examples-mo-sms/a9af544-SMS_Console_MO.png)
4. The list view will show both MT-SMS and MO-SMS messages. For both types, the **Status**, **Submitted**, **Finalized**, **Source Address** and **Payload** are shown. 5. A MO-SMS will remain in the pending status without being finalized until it was received and acknowledged by an SMS Forwarder Endpoint. As this integration is optional, by default the MO-SMS will stay in the pending state. *** ## 1NCE SMS API The 1NCE API offers another solution to access Mobile Originated SMS messages. For a specific SIM card a list of MT/MO-SMS or single SMS messages based on the SMS ID can be queried. A good starting point is the API Explorer to get familiar with the API calls. From the API Explorer, ready to use code snippets and cURL queries can be obtained to integrate into custom applications. ### API Prerequisites Before using the SMS API requests, an authentication token needs to be requested using the `/oauth/token` API request. For using the MT-SMS functionality, an ICCID of a 1NCE SIM is needed to send, monitor and manage the SMS messages for this SIM. ### Retrieving MO-SMS With the 1NCE SMS API, the received MO-SMS can be retrieved with some simple HTTP queries. Open the dropdowns below to see example guides for integration.
Get MT/MO-SMS List With the 1NCE API a list of MT/MO-SMS can be queried to get detailed information about the SMS message delivery status as well as have access to the payloads. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which a list of messages should be queried. 3. As a list of MT/MO-SMS messages will be returned, the **Page Size** parameter specifies how many list entries per loaded page will be returned. 4. As it is possible to have multiple pages, the **Page** parameter specifies the to be queried page. If there is more than one page present, the response header will include the total item count and the total page count. 5. The optional **Sort** parameter allows to sort the queried list to be sorted by the Status and IP Address keys. 6. Execute the **HTTP Get** request to query the MT/MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MO-SMS is shown. Please note that this query also shows any MT-SMS messages from the specified SIM. ```curl Query MO-SMS cURL Example curl --request GET \ --url 'https://api.1nce.com/management-api/v1/sims//sms?page=1&pageSize=10&sort=status%2Cip_address' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MO-SMS Response Example [ { "id": 7478676, "submit_date": "2021-12-01T12:13:52.000+0000", "delivery_date": "2021-12-01T12:13:52.000+0000", "expiry_date": "2021-12-02T12:13:52.000+0000", "retry_date": "2021-12-01T12:44:09.000+0000", "last_delivery_attempt": "2021-12-01T12:28:09.000+0000", "retry_count": "3", "source_address": "", "iccid": "", "msisdn": "", "imsi": "", "udh": "", "payload": "Another MO-SMS!", "status": { "id": 3, "description": "BUFFERED" }, "sms_type": { "id": 2, "description": "MO" }, "source_address_type": { "id": 145, "description": "International" } } ] ```
Get Individual MO-SMS Besides a list of MT/MO-SMS the 1NCE API allows to query specific SMS messages based on ICCD and SMS ID. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which the specific MO-SMS should be queried. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS. 4. Execute the **HTTP Get** request to query the specific MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MO-SMS is shown. ```curl Query MO-SMS cURL Example curl --request GET \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MO-SMS Response Example { "id": 7478676, "submit_date": "2021-12-01T12:13:52.000+0000", "delivery_date": "2021-12-01T12:13:52.000+0000", "expiry_date": "2021-12-02T12:13:52.000+0000", "retry_date": "2021-12-01T12:44:09.000+0000", "last_delivery_attempt": "2021-12-01T12:28:09.000+0000", "retry_count": "3", "source_address": "", "iccid": "", "msisdn": "", "imsi": "", "udh": "", "payload": "Another MO-SMS!", "status": { "id": 3, "description": "BUFFERED" }, "sms_type": { "id": 2, "description": "MO" }, "source_address_type": { "id": 145, "description": "International" } } ```
*** ## SIM Device MO-SMS MO-SMS messages are issued from devices which use a 1NCE SIM for connectivity. The SMS service is available without the need to establish a PDP Data Session. Please note that SMS is not possible with NB-IoT. ### MO-SMS with Smartphone For testing and trying out the SMS Service, 1NCE recommends to use a simple smartphone with a 1NCE SIM to send MO-SMS. 1. Insert the **1NCE SIM** into the smartphone used for testing. 2. Enable **Roaming**on the device, as the 1NCE SIM appears always as roaming. Ensure that a network connection is available through the network status indicator of the phone. 3. Open up the **SMS Messaging App** of the used smartphone. 4. The target **Phone Number** can be set to any arbitrary number as the 1NCE network ignores this parameter and forwards all MO-SMS to the Portal/API/SMS Forwarder. External phone numbers are not reachable. 5. Prepare a basic **SMS Message** and send the MO-SMS message. 6. Check in the 1NCE Portal, through the API or if implemented the SMS Forwarder to see the received MO-SMS. ### MO-SMS with IoT Devices Most IoT modem devices allow to send MO-SMS via AT Commands. Please check with the manufacturer documentation how to send MO-SMS or check the 1NCE Hardware & Modem Guides. --- # Mobile Terminated SMS Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-sms/examples-mt-sms/ ## 1NCE Portal / SMS Console This section covers the usage of the 1NCE Portal and the SMS Console to send MT-SMS to one individual 1NCE SIMs. The SMS Console only supports 7-Bit GSM Alphabet Text MT-SMS. For using more advanced features, please refer to the 1NCE API examples. ### Alphabet Text SMS Messages 1. Login to the 1NCE Portal and go the the **My SIMs** tab. 2. Select the **SIM** to which the MT-SMS messages should be issued from the list of all SIM cards. 3. Navigate to the **SMS Tab** at the bottom of the SIM details page to access the SMS Console.
![SMS_Console_01.png](/img/blueprints-examples/examples-sms/examples-mt-sms/c31f7b3-SMS_Console_01.png)
4. Enter a **Source Address**. This address is not needed for routing the SMS, but some devices might require a certain originating address/phone number to validate the sender. 5. Add a **7-Bit GSM Alphabet Text Payload** which should have a maximum length of **160 Characters**. Using the SMS Console only text messages with Data Coding Scheme (DCS) 0 and no Concatenated SMS are possible. Please refer to the 1NCE SMS API examples for more advanced features. 6. Click the **Send** button to issue the MT-SMS towards the 1NCE SIM device.
![SMS_Console_02.png](/img/blueprints-examples/examples-sms/examples-mt-sms/e08b43b-SMS_Console_02.png)
7. After sending the MT-SMS, please wait a bit as the message is being processed. The list view of the SMS messages can be manually updated. 8. While the MT-SMS is in transit and has not been acknowledged by the receiving device, the status is shown as **Pending**. 9. If the receiving device is attached to the network (not NB-IoT), the MT-SMS will be received, the status changes to **Delivered** and the **Finalized** timestamp will be shown. 10. If the receiving device is currently not attached, the MT-SMS will stay in the **Pending** state for up to 24 hours. The 1NCE network tries to redeliver this MT-SMS as soon as the devices becomes attached. After 24 hours, the MT-SMS will go the the **Failed** state and the SMS message will not be redelivered. *** ## 1NCE SMS API This section covers all topics around sending, monitoring and managing MT-SMS messages with the the 1NCE API. A good starting point is the API Explorer to get familiar with the API calls. From the API Explorer, ready to use code snippets and cURL queries can be obtained to integrate into custom applications. ### API Prerequisites Before using the SMS API requests, an authentication token needs to be requested using the `/oauth/token` API request. For using the MT-SMS functionality, an ICCID of a 1NCE SIM is needed to send, monitor and manage the SMS messages for this SIM. ### Sending MT-SMS The examples listed below show common use cases for sending MT-SMS with the 1NCE API. Please open the dropdowns to get a full guide on how to send these types of SMS messages.
7-Bit Alphabet Text SMS Messages This example show a simple MT-SMS message with a maximum 160 character 7-bit GSM Alphabet SMS message payload. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the 7-bit GSM Alphabet Text SMS Message. Please note the maximum length of the SMS is 160 characters. 5. For sending 7-bit GSM Alphabet SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 0. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a simple 7-bit GSM Alphabet MT-SMS message. ```curl 7-Bit Alphabetic MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "This is a MT-SMS message.", "dcs": 0, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
UCS-2 SMS Messages The Universal Coded Character Set (UCS-2) defines two bytes per encoded character. The example shown is similar to a normal 7-Bit GSM Alphabet MT-SMS with the needed DCS adaption and a shorter payload of 70 characters. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the UCS-2 MT-SMS Message. Please note the maximum length of the UCS-2 SMS is only 70 characters. 5. For sending UCS-2 SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 8. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a UCS-2 MT-SMS message. ```curl UCS-2 MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "UCS-2 MT-SMS message.", "dcs": 8, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
Binary SMS Messages Binary encoded MT-SMS messages are often used to send machine readable commands to a device in a compressed message. The payload of binary SMS messages need to be a HEX String and the Data Coding Scheme needs to be set to 4. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the Binary MT-SMS Message as HEX String. Please note the maximum length of the payload is 140 bytes. 5. For sending Binary SMS Messages, the **Data Coding Scheme (DCS)** needs to be set to 4. 6. The **User Data Header (UDH)** can be omitted for this simple type of SMS message. 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below is a cURL example for a Binary MT-SMS message. ```curl Binary MT-SMS cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "54657374534d53", "dcs": 4, "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
Concatenated SMS Messages All types of MT-SMS messages (7-Bit GSM Alphabet, Binary, UCS-2) can be send as a chain of concatenated SMS. The User Data Header (DH) is needed to inform the receiving device of the concatenated SMS. Please note that the usage of the UDH decreases the payload size by 6 bytes to 134 bytes (153 7-Bit characters). 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM to which the MT-SMS should be send in the HTTP Post URL. 3. The **Source Address** can be left empty or any numeric value can be supplied. For some devices this sender address/phone number is used for validation of the SMS source. This parameter is optional. 4. The **Payload** contains the MT-SMS Message. Please ensure that the maximum length matches the used payload type set in the DCS. 5. Specify the **Data Coding Scheme (DCS)** according to the desired payload time. 6. The **User Data Header (UDH)** is a 6 byte value encoded as HEX String. The first 4 bytes contain the UDH length, Information Element Identifier, header length without the first two fields, CSMS reference ID, total SMS Parts and current Part Number. The last two fields need to be altered based on the total amount of concatenated SMS messages and the current SMS Part Number. The table below shows an example UDH for a 3 part Concatenated SMS. | UHD Field | Example | | :----------------------------- | :------ | | UDH Length | 0x05 | | Information Element Identifier | 0x00 | | UDH Header Length - 2 Byte | 0x03 | | CSMS Reference ID | 0xCC | | SMS Part Count | 0x03 | | Current SMS Part (1/3) | 0x01 | 7. Set the **Source Address Type** according to the used Source Address. The value 145 is fine for numeric values. Please use 208 for alphanumeric Source Addresses. This parameter is optional. 8. The **Expiry Date** in ISO8601 format sets the timepoint until the retry mechanism will try to deliver a MT-SMS before it will go into the *Failed* state. A MT-SMS is only delivered if the target SIM device is attached to the network and can receive SMS messages. This parameter is optional. 9. Execute the **HTTP Post** request to issue the MT-SMS towards the SIM device. Shown below in the separate tabs are three the cURL example for a a three part concatenated MT-SMS. ```curl Concatenated MT-SMS Part 01 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 01", "dcs": 0, "udh": "050003CC0301", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ``` ```curl Concatenated MT-SMS Part 02 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 02", "dcs": 0, "udh": "050003CC0302", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ``` ```curl Concatenated MT-SMS Part 03 cURL Example curl --request POST \ --url https://api.1nce.com/management-api/v1/sims//sms \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json;charset=UTF-8' \ --data ' { "source_address": "123456", "payload": "Message Part 03", "dcs": 0, "udh": "050003CC0303", "source_address_type": { "id": 145 }, "expiry_date": "2021-12-12T16:10:29.000+0000" } ' ```
### Monitoring MT-SMS Besides sending different types MT-SMS, the API can also be used to monitor and obtain a list of issued MT-SMS messages. Expand the dropdowns below to see the possibilities of querying the MT-SMS API.
Get MT/MO-SMS List With the 1NCE API a list of MT/MO-SMS can be queried to get detailed information about the SMS message delivery status as well as have access to the payloads. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which a list of messages should be queried. 3. As a list of MT/MO-SMS messages will be returned, the **Page Size** parameter specifies how many list entries per loaded page will be returned. 4. As it is possible to have multiple pages, the **Page** parameter specifies the to be queried page. If there is more than one page present, the response header will include the total item count and the total page count. 5. The optional **Sort** parameter allows to sort the queried list to be sorted by the Status and IP Address keys. 6. Execute the **HTTP Get** request to query the MT/MO-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MT-SMS in the second tab is shown. Please note that this query also shows any MO-SMS messages from the specified SIM. ```curl Query MT-SMS cURL Example curl --request GET \ --url 'https://api.1nce.com/management-api/v1/sims//sms?page=1&pageSize=10&sort=status%2Cip_address' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MT-SMS Response Example [ { "id": 7476638, "submit_date": "2021-12-01T07:43:34.000+0000", "delivery_date": "2021-12-01T07:43:34.000+0000", "expiry_date": "2021-12-02T07:43:34.000+0000", "final_date": "2021-12-01T07:43:35.000+0000", "last_delivery_attempt": "2021-12-01T07:43:35.000+0000", "retry_count": "0", "source_address": "1234567", "iccid": "", "msisdn": "", "imsi": "", "msc": "", "udh": "", "payload": "This is a 1NCE MT-SMS Test!", "status": { "id": 4, "description": "DELIVERED" }, "sms_type": { "id": 1, "description": "MT" }, "source_address_type": { "id": 161, "description": "National" } } ] ```
Get Individual MT-SMS Besides a list of MT/MO-SMS the 1NCE API allows to query specific SMS messages based on ICCD and SMS ID. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM of which the specific MT-SMS should be queried. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS or from the Location Response Header of the Send MT-SMS HTTP Post request. 4. Execute the **HTTP Get** request to query the specific MT-SMS messages. In the code example below, a sample HTTP Get cURL request and a corresponding response for a MT-SMS in the second tab is shown. ```curl Query MT-SMS cURL Example curl --request GET \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```curl Query MT-SMS Response Example { "id": 7476638, "submit_date": "2021-12-01T07:43:34.000+0000", "delivery_date": "2021-12-01T07:43:34.000+0000", "expiry_date": "2021-12-02T07:43:34.000+0000", "final_date": "2021-12-01T07:43:35.000+0000", "last_delivery_attempt": "2021-12-01T07:43:35.000+0000", "retry_count": "0", "source_address": "1234567", "iccid": "", "msisdn": "", "imsi": "", "msc": "", "udh": "", "payload": "This is a 1NCE MT-SMS Test!", "status": { "id": 4, "description": "DELIVERED" }, "sms_type": { "id": 1, "description": "MT" }, "source_address_type": { "id": 161, "description": "National" } } ```
### Manage MT-SMS Through the API, issued MT-SMS that have not been delivered yet can be deleted from the SMS queue. The dropdown below show how to use the SMS API to manage MT-SMS.
Delete MT-SMS A MT-SMS that has not been delivered and is currently in the retry loop, can be delete using the 1NCE SMS API. 1. Obtain the **API Authentication Token** for the 1NCE API using the */oauth/token* API request. Supply the Token in the *Authorization: Bearer* header value. 2. Enter the **ICCID** of the SIM for which a MT-SMS should be deleted. 3. The **SMS ID** uniquely identifies each SMS message. This ID can be obtained from the list of MT/MO-SMS or from the Location Response Header of the Send MT-SMS HTTP Post request. 4. Execute the **HTTP Delete** to delete the buffered MT-SMS. In the code example below, a sample HTTP Delete cURL request to delete a buffered MT-SMS is shown. ```curl Delete MT-SMS cURL Example curl --request DELETE \ --url https://api.1nce.com/management-api/v1/sims//sms/ \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ```
*** ## SIM Device MT-SMS MT-SMS messages are issued towards devices which use a 1NCE SIM for connectivity. The SMS service is available without the need to establish a PDP Data Session. Please note that SMS is not possible with NB-IoT. ### MT-SMS with Smartphone For testing and trying out the SMS Service, 1NCE recommends to use a simple smartphone with a 1NCE SIM to receive MT-SMS. 1. Insert the **1NCE SIM** into the smartphone used for testing. 2. Enable **Roaming** on the device, as the 1NCE SIM appears always as roaming. Ensure that a network connection is available through the network status indicator of the phone. 3. Open up the **SMS Messaging App** of the used smartphone. 4. Prepare a **SMS Message** using one of the above mentioned methods (1NCE Portal or 1NCE API) to issue a MT-SMS. 5. Send the message towards the specific **ICCID SIM** which is inserted in the smartphone. 6. Check the smartphone for an incoming SMS message. ### MT-SMS with IoT Devices Most IoT modem devices can receive and save MT-SMS. The control of the SMS management on the modem side is handled via AT Commands. Please check with the manufacturer documentation how to receive and query MT-SMS or check the 1NCE Hardware & Modem Guides. --- # VPN Service Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-vpn/ Each 1NCE SIM has a private IP and is connected via the Internet Breakout using Network Address Translation to the open internet. By default the connection establishment is unidirectional from the SIM device to a server/service in the internet. The 1NCE VPN Service enables 1NCE customers to connect and transmit data bidirectional with their SIM devices via a Virtual Private Network (VPN) connection. This section covers the setup of the 1NCE VPN client for Windows, Linux and Mac OS to establish a connection with the 1NCE Network Service. For custom OpenVPN installs, advanced routing or specific application setups refer to the OpenVPN Documentation. *** # Setup Guides For a detailed guide on how to install the VPN Client click on one of the following Operating Systems:
![](/img/blueprints-examples/examples-vpn/13f2388-windows.svg)
--- # VPN Setup Linux Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-vpn/examples-vpn-linux/
![](/img/blueprints-examples/examples-vpn/examples-vpn-linux/001.png)
Linux is very popular as a server operating system, thus it is used in many production systems for running applications. The 1NCE VPN service can be used with the OpenVPN client for Linux. This section covers the general installation and operation procedure of OpenVPN using the 1NCE VPN Service. Please note that due to the many flavors of the Linux operating system, the install procedure might be different for other Linux flavors. In the example, Ubuntu is used as operating system and the install process is carried out via Command Line Interface (CLI). Please keep the `xx-region-x-client.conf` and the `credentials.txt` file downloaded from the 1NCE Portal at hand to get started. A current version of the OpenVPN client for Windows needs to be installed. For this please download the latest version from the OpenVPN Download Portal. *** # Linux Routing & Interface Each 1NCE SIM has a fixed IP from the private IP space (RFC 1597) allocated. The connected VPN client also has a static address from the private IP space assigned. Please note that these addresses might not necessarily be from the same subnet, which has no impact on the functionality. > 📘 Pushed Routes and Updates > > The routing for all assigned SIM IP Subnets is pushed during the initialization of the connection. If new IP spaces are assigned as a result of a larger SIM order, please restart the VPN connection to obtain the latest routes. The customer specific traffic routing from the VPN terminating client to the specific applications/servers interfaces needs to be set up on configured by the customer and is specific to the application case. An example of IP routes pushed from the VPN server to the client are listed below. Please note that the IP addresses in the following examples are just illustrative and may not be the same as in your configuration. A short snippet from the OpenVPN log file obtained during the start of a VPN connection. It shows the routes being pushed towards the Linux VPN interface. ```text Fri Jan 28 08:42:19 2022 /sbin/ip link set dev tun0 up mtu 1500 Fri Jan 28 08:42:19 2022 /sbin/ip addr add dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/32 via x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/24 via x.x.x.x ``` Tunnel Adapter of the OpenVPN connection in Linux shows the VPN client IP address. This address should be used to connect with a SIM card to the VPN client/customer server. ```text tun0: flags=4305 mtu 1500 inet 10.66.x.x netmask 255.255.255.255 destination 10.66.x.x inet6 fe80::dde8:427c:xxxx:xxxx prefixlen 64 scopeid 0x20 unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 100 (UNSPEC) RX packets 0 bytes 0 (0.0 B) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 1 bytes 48 (48.0 B) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 ``` Output of `route` in Linux CLI shows the current routes configured on the system. OpenVPN pushed the routes towards the SIMs after a VPN connection has been established. Please ensure that there are not local IP address conflicts within the network and SIM IP ranges. ```text Kernel IP routing table Destination Gateway Genmask Flags Metric Ref Use Iface 10.64.x.x 10.66.x.x 255.255.255.255 UGH 0 0 0 tun0 10.66.x.x 0.0.0.0 255.255.255.255 UH 0 0 0 tun0 10.210.x.x 10.66x.x 255.255.255.0 UG 0 0 0 tun0 ``` Connecting the VPN client on Linux machine creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. *** # Linux VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. To install and operate the Linux OpenVPN client, the example uses the Command Line Interface (CLI) to configure the 1NCE VPN Service. Please keep the configuration and credentials file from the 1NCE Portal at hand. 1. Ensure that the operating system is up-to-date and the latest package sources are available. ```text Ubuntu Update sudo apt update sudo apt upgrade ``` 2. Install OpenVPN using the system packet manager. Optionally a custom OpenVPN version can be build from source code if needed. ```text Open VPN Install sudo apt install openvpn ``` 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Linux/MacOS** as configuration medium and download the OpenVPN *xx-region-x-client.conf* and *credentials.txt* files.
![1nce-vpn-linux.png](/img/blueprints-examples/examples-vpn/examples-vpn-linux/d5055b7-1nce-vpn-linux.png)
4. Place the *xx-region-x-client.conf* and *credentials.txt* in the OpenVPN configuration folder, typically */etc/openvpn/*. 5. Optionally rename the *xx-region-x-client.conf* and *credentials.txt* files to make their names unique and more transparent. 6. If required, change the path of the *credentials.txt* file in the *xx-region-x-client.conf* on line *auth-user-pass*. This is needed if the credentials file is placed somewhere else besides the default location or if the files were renamed. 7. Make any alterations to the VPN configuration (e.g. add logging or custom parameters) before starting the client the first time. 8. As a first run, start the VPN client directly in the CLI and not as a service. This will provide a direct output of the logs and makes debugging easier. Adapt the path to the configuration file to the location and filename of the used config files. ```text OpenVPN Start sudo openvpn --config /etc/openvpn/1nce-conf.conf ``` ```text OpenVPN Connection Log Fri Jan 28 08:42:12 2022 OpenVPN 2.4.7 x86_64-pc-linux-gnu [SSL (OpenSSL)] [LZO] [LZ4] [EPOLL] [PKCS11] [MH/PKTINFO] [AEAD] built on Jul 19 2021 Fri Jan 28 08:42:12 2022 library versions: OpenSSL 1.1.1f 31 Mar 2020, LZO 2.10 Fri Jan 28 08:42:12 2022 TCP/UDP: Preserving recently used remote address: [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 Socket Buffers: R=[212992->212992] S=[212992->212992] Fri Jan 28 08:42:12 2022 UDP link local: (not bound) Fri Jan 28 08:42:12 2022 UDP link remote: [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 NOTE: UID/GID downgrade will be delayed because of --client, --pull, or --up-delay Fri Jan 28 08:42:12 2022 TLS: Initial packet from [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:12 2022 VERIFY OK: depth=1, C=de, ST=North Rhine-Westphalia, L=Cologne, O=1nce, OU=1nce Operations, CN=x, name=1nce Fri Jan 28 08:42:12 2022 VERIFY KU OK Fri Jan 28 08:42:12 2022 Validating certificate extended key usage Fri Jan 28 08:42:12 2022 ++ Certificate has EKU (str) TLS Web Server Authentication, expects TLS Web Server Authentication Fri Jan 28 08:42:12 2022 VERIFY EKU OK Fri Jan 28 08:42:12 2022 VERIFY OK: depth=0, C=de, ST=North Rhine-Westphalia, L=Cologne, O=1nce, OU=1nce Operations, CN=x, name=1nce Fri Jan 28 08:42:13 2022 Control Channel: TLSv1.3, cipher TLSv1.3 TLS_AES_256_GCM_SHA384, 2048 bit RSA Fri Jan 28 08:42:13 2022 [x] Peer Connection Initiated with [AF_INET]x.x.x.x:1194 Fri Jan 28 08:42:14 2022 SENT CONTROL [x]: 'PUSH_REQUEST' (status=1) Fri Jan 28 08:42:19 2022 SENT CONTROL [x]: 'PUSH_REQUEST' (status=1) Fri Jan 28 08:42:19 2022 PUSH: Received control message: 'PUSH_REPLY,route x.x.x.x,topology net30,ping 5,ping-restart 30,route x.x.x.x x.x.x.x,ifconfig x.x.x.x x.x.x.x,peer-id 322,cipher AES-256-GCM' Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: timers and/or timeouts modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: --ifconfig/up options modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: route options modified Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: peer-id set Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: adjusting link_mtu to 1624 Fri Jan 28 08:42:19 2022 OPTIONS IMPORT: data channel crypto options modified Fri Jan 28 08:42:19 2022 Data Channel: using negotiated cipher 'AES-256-GCM' Fri Jan 28 08:42:19 2022 Outgoing Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key Fri Jan 28 08:42:19 2022 Incoming Data Channel: Cipher 'AES-256-GCM' initialized with 256 bit key Fri Jan 28 08:42:19 2022 ROUTE_GATEWAY x.x.x.x/x.x.x.x IFACE=ens3 Fri Jan 28 08:42:19 2022 TUN/TAP device tun0 opened Fri Jan 28 08:42:19 2022 TUN/TAP TX queue length set to 100 Fri Jan 28 08:42:19 2022 /sbin/ip link set dev tun0 up mtu 1500 Fri Jan 28 08:42:19 2022 /sbin/ip addr add dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/32 via x.x.x.x Fri Jan 28 08:42:19 2022 /sbin/ip route add x.x.x.x/24 via x.x.x.x Fri Jan 28 08:42:19 2022 GID set to nogroup Fri Jan 28 08:42:19 2022 UID set to root Fri Jan 28 08:42:19 2022 Initialization Sequence Completed ^C Fri Jan 28 08:42:21 2022 event_wait : Interrupted system call (code=4) Fri Jan 28 08:42:21 2022 SIGTERM received, sending exit notification to peer Fri Jan 28 08:42:24 2022 /sbin/ip route del x.x.x.x/32 Fri Jan 28 08:42:24 2022 /sbin/ip route del x.x.x.x/24 Fri Jan 28 08:42:24 2022 Closing TUN/TAP interface Fri Jan 28 08:42:24 2022 /sbin/ip addr del dev tun0 local x.x.x.x peer x.x.x.x Fri Jan 28 08:42:24 2022 SIGTERM[soft,exit-with-notification] received, process exiting ``` 9. OpenVPN will start and try to connect to the VPN server. The logs (see second tab) will be printed to the CLI and show the current connection status. If there are any unexpected errors, check the configuration and setup and please try again. 10. The connection can be closed by CTRL+C. 11. To run the 1NCE VPN with OpenVPN client as a system service in the background, use the `sytemctl` commands. Ensure that the config name provided to start the VPN client matches the filename in `/etc/openvpn/`. Note that the `.conf` extension needs to be omitted. ```text sudo systemctl start openvpn@1nce-conf sudo systemctl status openvpn@1nce-conf sudo systemctl restart openvpn@1nce-conf sudo systemctl stop openvpn@1nce-conf ``` 12. Once the service is up and running, the status can be queried to see the current VPN connection status. 13. To restart or stop the VPN client, use the `restart` or `stop` command. If a successful connection is established, the Linux system should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. *** # Monitoring and Logging The 1NCE VPN Service on Linux with OpenVPN allows for easy monitoring and optional logging. This is especially useful for debugging the VPN setup in case of connectivity issues. By default, the VPN connection towards the 1NCE Network is updated once per hour. This renewal process should be logged in the monitoring. If this renewal happens very frequently, it might point towards an unstable connection or two VPN clients fighting for the same single connection. ## Extended Logging For extended logging over longer periods of time or with a defined information granularity, the *xx-region-x-client.conf* configuration needs to be adapted. The example below shows possible configuration parameters.\ The Verbosity *verb\* defines the amount of detail included in the log file. The default value of 3 offers a good mix between detail and abstraction. The settable range is 1 to 4. Please note that setting the log level to 4 will generate larger log files.\ The path where a log file will be saved is specified by *log\/openvpn.log*. Please adapt the path to a valid place in Linux to store the logs.\ Log files can be automatically rotated. The example shown below provides a basic starting point for weekly log file rotation. For more information please see OpenVPN Documentation. ```text verb log /openvpn.log /openvpn.log { weekly rotate 12 copytruncate compress delaycompress missingok notifempty } ``` --- # VPN Setup Mac OS Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-vpn/examples-vpn-macos/
![](/img/blueprints-examples/examples-vpn/examples-vpn-macos/001.png)
For using the 1NCE VPN Service with Mac OS, it is recommended to use the Tunnelblick application. If offers an easy to configure and use interface for OpenVPN client connectivity. Please refer to Tunnelblick for more details about the Mac OS OpenVPN client. *** # Mac OS VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. 1. Download the current version of the **Tunnelblick** client for Mac OS. (Tunnelblick Download 2. Install the the OpenVPN client for Mac OS. Follow the default install instructions. 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Mac OS** as configuration medium and download the OpenVPN *xx-region-x-client.conf* and *credentials.txt* files.
![1nce-vpn-linux.png](/img/blueprints-examples/examples-vpn/examples-vpn-macos/35112bd-1nce-vpn-linux.png)
4. Import the *xx-region-x-client.conf* and *credentials.txt* into Tunnelblick application. Refer to Tunnelblick Install Guide for details about the setup. 5. Once the configuration is installed. The connection can be established by clicking on *Connect* inside the application. 6. A new pop-up will be shown for the client connecting. It shows the logs of the current connection attempt. After a few seconds the client should connect and the pop-up should be closed automatically. The VPN connection can be terminated by clicking **Disconnect** in the OpenVPN task bar menu. If a successful connection is established, the computer should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. --- # VPN Setup Windows Source: https://help.1nce.com/docs/v2/blueprints-examples/examples-vpn/examples-vpn-windows/
![](/img/blueprints-examples/examples-vpn/examples-vpn-windows/001.png)
The Windows platform is often used for testing on personal computers or in a Windows Server environment. This section covers the basic setup the 1NCE VPN Service on a Windows PC. Further the data routing needed for communicating between the VPN client and the 1NCE SIMs is shown. References to examples for testing and debugging the Windows VPN integrations are provided. Please keep the `xx-region-x-client.ovpn` and the `credentials.txt` file downloaded from the 1NCE Portal at hand to get started. A current version of the OpenVPN client for Windows needs to be installed. For this please download the latest version from the OpenVPN Download Portal. *** # Windows Routing & Interface Each 1NCE SIM has a fixed IP from the private IP space (RFC 1597) allocated. The connected VPN client also has a static address from the private IP space assigned. Please note that these addresses might not necessarily be from the same subnet, which has no impact on the functionality. > 📘 Pushed Routes and Updates > > The routing for all assigned SIM IP Subnets is pushed during the initialization of the connection. If new IP spaces are assigned as a result of a larger SIM order, please restart the VPN connection to obtain the latest routes. The customer specific traffic routing from the VPN terminating client to the specific applications/servers interfaces needs to be set up on configured by the customer and is specific to the application case. An example of IP routes pushed from the VPN server to the client are listed below. Please note that the IP addresses in the following examples are just illustrative and may not be the same as in your configuration. A short snippet from the OpenVPN log file obtained during the start of a VPN connection using a Windows PC. It shows the routes being pushed towards the Windows system. ```text Notified TAP-Windows driver to set a DHCP IP/netmask of 10.64.80.2/255.255.255.252 on interface {ACF7A788-1EF1-43D2-9CE4-240945672EF6} [DHCP-serv: 10.64.80.2, lease-time: 31536000] Successful ARP Flush on interface [14] {ACF7A788-1EF1-43D2-9CE4-240945672EF6} MANAGEMENT: >STATE:1621401048,ASSIGN_IP,,10.64.80.2,,,, ROUTES: 2/2 succeeded len=2 ret=1 a=0 u/d=up MANAGEMENT: >STATE:1621401053,ADD_ROUTES,,,,,, C:\WINDOWS\system32\route.exe ADD 10.64.0.1 MASK 255.255.255.255 10.64.80.2 Route addition via service succeeded C:\WINDOWS\system32\route.exe ADD 10.119.x.x MASK 255.255.252.0 10.64.80.2 ``` Tunnel Adapter of the OpenVPN connection in Windows shows the VPN client IP address. This address should be used to connect with a SIM card to the VPN client/customer server. ```text Connection-specific DNS suffix: Link-local IPv6 Address . : fe80::xxxx:xxxx:xxxx:xxxx IPv4 Address . . . . . . . . . . : 10.64.80.2 Subnet Mask . . . . . . . . . . : 255.255.255.252 Default Gateway . . . . . . . . . : ``` Output of `route print` in Windows Command Line shows the current routes configured on the system. OpenVPN pushed the routes towards the SIMs after a VPN connection has been established. Please ensure that there are not local IP address conflicts within the network and SIM IP ranges. ```text IPv4 Routen Table =========================================================================== Active Routes: Network Destination Netmask Gateway Interface Metric 10.64.0.1 255.255.255.255 10.64.80.3 10.64.80.1 4506 10.64.80.1 255.255.255.252 On-Link 10.64.80.1 4506 10.64.80.2 255.255.255.255 On-Link 10.64.80.1 4506 10.64.80.4 255.255.255.255 On-Link 10.64.80.1 4506 10.119.x.x 255.255.252.0 10.64.80.3 10.64.80.1 4506 224.0.0.0 240.0.0.0 On-Link 10.64.80.1 4506 255.255.255.255 255.255.255.255 On-Link 10.64.80.1 4506 ``` Connecting the VPN client on PC or server creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. *** # Windows VPN Client Setup > 📘 VPN Connection Limit > > Please note that only once OpenVPN client towards the 1NCE Network connection at a time can be open at any given time. If multiple OpenVPN client connect with the same credentials at the same time, the connectivity will be inconsistent and dropped. Ensure to terminate any unused OpenVPN client connection before establishing a new connection. The Windows platform is often used for testing on personal computers or in a Windows Server environment. In this section, the configuration of the 1NCE VPN Service for the Windows Operating System is shown. 1. Download the current version of the **OpenVPN** client for Windows. (OpenVPN Download 2. Install the the OpenVPN client for Windows. Follow the default install instructions. 3. Log into the **1NCE Portal**. Navigate to the **Configuration** tab and open the **OpenVPN Configuration** dropdown. Select **Windows** as configuration medium and download the OpenVPN *xx-region-x-client.ovpn* and *credentials.txt* files.
![VPN_Windows_Configuration_01.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/d5ac052-VPN_Windows_Configuration_01.png)
4. Place the *xx-region-x-client.ovpn* and *credentials.txt* in the OpenVPN configuration folder, typically *C:\\Program Files\\OpenVPN\\config*. 5. If required, change the path of the *credentials.txt* file in the *xx-region-x-client.ovpn* on line *auth-user-pass*. This is needed if the credentials file is placed somewhere else besides the default location. 6. Optionally, rename the *xx-region-x-client.ovpn* file to make it unique in the OpenVPN user interface. 7. Start the **OpenVPN GUI** program. Typically it will open in the task bar. 8. Right click the **OpenVPN Icon** in the task bar menu. 9. If more than one client is configured, a list of VPN connections is shown. 10. Select the desired *client*, renamed configuration or if only one client is configured click on **Connect**.
![VPN_Windows_Configuration_02.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/6b2e31c-VPN_Windows_Configuration_02.png)
11. A new pop-up will be shown for the client connecting. It shows the logs of the current connection attempt. After a few seconds the client should connect and the pop-up should be closed automatically.
![VPN_Windows_Configuration_03.png](/img/blueprints-examples/examples-vpn/examples-vpn-windows/e950072-VPN_Windows_Configuration_03.png)
The VPN connection can be terminated by clicking **Disconnect** in the OpenVPN task bar menu. If a successful connection is established, the computer should now be ready to ping and establish connection towards active/connected 1NCE SIM with an open PDP data session. *** # Monitoring and Logging The 1NCE VPN Service on Windows with OpenVPN allows for easy monitoring and optional logging. This is especially useful for debugging the VPN setup in case of connectivity issues. By default, the VPN connection towards the 1NCE Network is updated once per hour. This renewal process should be logged in the monitoring. If this renewal happens very frequently, it might point towards an unstable connection or two VPN clients fighting for the same single connection. ## Current Session Logs Right click on the task tray icon and select **View Log**. This will bring up the log of the currently established connection. In the logs, details about the connection setup, reconnect, keep-alive and pushed routes can be found. Please always include these logs in any VPN related Support Ticket. ## Extended Logging For extended logging over longer periods of time or with a defined information granularity, the *xx-region-x-client.ovpn* configuration needs to be adapted. The example below shows possible configuration parameters.\ The Verbosity *verb\* defines the amount of detail included in the log file. The default value of 3 offers a good mix between detail and abstraction. The settable range is 1 to 4. Please note that setting the log level to 4 will generate larger log files.\ The path where a log file will be saved is specified by *log\/openvpn.log*. Please adapt the path to a valid place in Windows to store the logs.\ Log files can be automatically rotated. The example shown below provides a basic starting point for weekly log file rotation. For more information please see OpenVPN Documentation. ```text verb log /openvpn.log /openvpn.log { weekly rotate 12 copytruncate compress delaycompress missingok notifempty } ``` --- # Data Services Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-data-services/
![Schematic overview of the 1NCE data service network structue.](/img/connectivity-services/connectivity-services-data-services/001.png)
The fundamental concept of IoT connectivity refers to millions of devices being connected to the internet and the device capabilities to exchange data packets with other connected services. With a 1NCE SIM, devices can talk to any internet service with a wide variety of data protocols and use this free connectivity to their advantage. Additional features offered by the 1NCE data services provide increased security and usability, but minor limitations for the specific IoT application need to be taken into consideration. In the following sections of this guide, a basic introduction to the features, limitations, terminology, and detailed applications of the data service is provided. For more details about this service, refer to the subchapters in the menu on the left side. As an overview, a good starting point is the [Features & Limitations](/docs/connectivity-services/connectivity-services-data-services/data-services-features-limitations) section to get a better understanding of the possibilities with the 1NCE data service. After mastering these sections, the individual application sections provide an in-depth insight into the setup and implementation of the data service-related features such as [APN Setup](/docs/connectivity-services/connectivity-services-data-services/data-services-apn), [Data Monitoring](/docs/connectivity-services/connectivity-services-data-services/data-services-data-monitoring), and general information about the [Data Volume](/docs/connectivity-services/connectivity-services-data-services/data-services-data-volume). --- # APN Setup Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-data-services/data-services-apn/ An Access Point Name (APN) is defined as the name of the gateway between a mobile network and a core network. The APN specifies to which network and what exact type of network a connection should and can be established. In common mobile networks, the APN defines the name of the gateway which enables the connection towards the open internet. This setting needs to be configured for each device that wants to communicate with an internet service. *** # 1NCE APN Setup > ❗️ APN Setting Required! > > As 1NCE is providing multiple APNs, it is mandatory that a APN is configured. Without a correct APN set, it can not be guaranteed that a device will have a Data Connection. Auto APN configuration is NOT supported. How the APN needs to be configured is dependent on the specific device used with a 1NCE SIM. While most devices only require the APN in URL format, some specific devices require additional parameters to be set. The parameters to set are listed in the table below. Please note that the APN is mandatory to be set and some other parameters are optional or cannot be set manually. | Setting | Value | | :-------------------- | :------------------------------------- | | APN | **sensor.net** | | Username | Not Required, Leave Empty | | Password | Not Required, Leave Empty | | Authentication Method | Password Authentication Protocol (PAP) | | Internet Protocol | Internet Protocol Version 4 (IPv4) | ## 1NCE Access Point Name This parameter needs to be set in the devices with a 1NCE SIM. Please refer to the device manufacturer for a guide on how to set an APN. In most cases, this can be done by a specific AT Command, sending a SMS to the device or via the device user interface. ## Authentication Some devices might require the authentication method setting, username, and password. This authentication procedure can be requested by each side of the connection as part of the establishment process. The two most common authentication procedures are Password Authentication Protocol (PAP) and Challenge Handshake Authentication Protocol (CHAP). PAP is the older protocol and is based on a simple username and password authentication. CHAP is a more sophisticated and more secure authentication method based on randomly generated challenges.\ For the 1NCE APN no username or password is needed. These parameters can be left empty in the configuration. The authentication method PAP should be selected as default if the device requires this parameter. ## Internet Protocol Some devices support both Internet Protocol versions IPv4 and IPv6. The 1NCE core network currently only supports IPv4 for the time being. Therefore, IPv4 must be used. --- # Data Monitoring Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-data-services/data-services-data-monitoring/ When monitoring the data service offered by the 1NCE SIM connectivity, there is more to explore than just tracking the usage volume. Through different means of the 1NCE Portal, [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) and [1NCE API](/api/), the usage volume, data session connection state and device connectivity can be monitored. In the following sections, the capabilities and benefits of each available interface is presented. *** # 1NCE Portal The web portal is a ready-to-use interface for monitoring all 1NCE services. The current status of the data session (PDP context), the overall volume usage, and status messages can be viewed for each SIM. Event records from the data streamer are listed in the web interface. This provides an overview of the state of the 1NCE SIM. The online portal offers a starting point for non-automated monitoring of small batches of SIM or fast debugging of connections. This platform offers no integration possibilities and the logging data is deleted after seven days due to the data retention policy. For more details on how to use the 1NCE Portal, please refer to the [Portal Guide](/docs/1nce-portal/portal-dashboard). *** # Data Streamer The [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) delivers a stream of the event and/or usage records via a wide selection of cloud connectivity applications. The main application case is long-term, automated monitoring of large amount of connected SIM. For the data service, usage volume and event records are part of the stream. Usage records are generated at regular intervals and the end of a data session. The event records show the general connectivity of the device to the mobile network and the creation and deletion of a data session. In the events warnings and errors from the network core are included to ease debugging possibilities. More details are covered in the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) of this guide. *** # 1NCE API The 1NCE API is a powerful tool for querying certain information parameters on demand. An example for the data service is accumulated volume usage records for each SIM card on different time scales. The data usage limits can be requested and set via the API. Furthermore, the current state of the overall available volume and used quota can be queried, and if needed volume top-ups initiated. Please note that certain data will be retained only a fixed amount of time due to the data retention policy. The 1NCE API is ideal for requesting specific information on demand. It is not recommended to use this interface for large, automated queries regularly, please use the data streaming service for this kind of automation. Details about the API can be found in the [API guide](/api/) section of the documentation. --- # Data Volume Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-data-services/data-services-data-volume/ Based on the specific tariff of the 1NCE SIM, a set amount of data volume is included. The used and available volume for each of the SIM can be viewed in the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) or queried through [1NCE API](/api/). The following sections will explain what data volume usage is deducted from the volume and how this can be calculated for some protocols. *** ## Data Volume Usage When using the 1NCE data service, both uplink (UL) and downlink (DL) data transmissions are counted towards the used volume. Taking a look at the different layers in the communication in the figure below, only the traffic inside the GTP is considered for billing. The IP overhead, specific network protocol (e.g., TCP, UDP, MQTT, etc.) overhead, and actual payload size account as data usage. For sending large data packets, IP fragmentation generates further overhead data traffic. It does not matter if the 1NCE VPN service or a direct internet breakout is used as this does not constitute a difference in the usage data.
![Schematic description of the data service layers and their volume usage.](/img/connectivity-services/connectivity-services-data-services/data-services-data-volume/001.png)
Important to note is that besides the overhead for sending a payload, additional data transfers for the connection establishment, synchronize, acknowledge, or retransmission exchanges dependent on the used network protocols need to be accounted for in the data usage. This additional overhead is hard to estimate as it is depended on many other factors (e.g., wireless data link quality, latency, etc.). Example calculations for some of the most commonly used protocols are shown in the [example scenarios](#example-scenarios). *** ## Self-Set Data Volume Limits A customer-specified limit for the data volume can be set in the 1NCE Portal Configuration tab or through the 1NCE API. This limit applies to the usage of data volume for all SIM in the organization. These limits can be used to restrict the data volume usage per month for the SIMs from the network side. The limits can be set in predetermined steps and will be reset on the first day of each new month. ### Reaching and Resetting the Limit If a SIM runs into this limitation, an Event Record **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** will be generated when attempting to create a new data session. Further a customer notification will be generated. To reenable a SIM, please either wait until the volume is reset at the beginning of the month or manually increase the limit via the 1NCE Portal or 1NCE API. > ❗️ Error Warning Exceeded Limit > > When the limit is reached new PDP data sessions will be rejected:\ > **PDP Context Request rejected, because endpoint is currently blocked due to exceeded traffic limit.** > > Please note that some devices might retry indefinitely to reconnect in such a case. 1NCE strongly advices to use a back-off approach in this rejection case to not flood the network with PDP session requests. *** ## Example Scenarios To provide a better understanding of the estimation of data volume usage, a few examples with commonly used network protocols are listed below. ### DNS Resolution When using URLs as a reference, these have to be resolved via a DNS request to obtain the target IP address. This resolution process generates additional traffic which is often overlooked in the usage calculation. The table shown an example data usage for one DNS resolution. Dependent on the IoT device software, multiple DNS queries might be executed as part of a normal operation. > 📘 Avoiding DNS Resolution > > It is possible to avoid the DNS resolution if the IP address of the destination is known. In this case, the device should be configured to send data to the IP instead of the DNS. > > However, this comes with a risk. For example, the application may stop working should the IP change. Usually, the DNS stays the same but point to the correct IP, even when a new IP is being used.\ > As such, there is a risk that at some point of time data is not reaching its intended destination as the IP was reassigned. Therefore, we generally recommend using the address "udp.os.1nce.com" instead of the IP behind the DNS. | Description | DNS/UDP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **DNS Resolution** | **94 Bytes** | **40 Bytes** | **134 Bytes** | | *DNS Query* e.g. [www.google.de](http://www.google.de) | 39 Bytes | 20 Bytes | 59 Bytes | | *DNS Response* | 55 Bytes | 20 Bytes | 75 Bytes | ### Transmission Control Protocol (TCP) In this use case, the minimal TCP network protocol is used to send a payload of 100 bytes of data from a device towards a server. Afterward, 50 bytes are returned from the server towards the device. The shown calculation is based on the assumption that no retransmissions will be needed. Depending on the application and the used header options for TCP and IP, the size of these packets will be larger. | Description | TCP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **3-Way Handshake** | **64 Bytes** | **60 Bytes** | **124 Bytes** | | *SYN* | 20 Bytes | 20 Bytes | 40 Bytes | | *SYN/ACK* | 24 Bytes | 20 Bytes | 44 Bytes | | *SYN* | 20 Bytes | 20 Bytes | 40 Bytes | | **Payload Exchange** | **230 Bytes** | **80 Bytes** | **310 Bytes** | | *PSH/ACK* *100 Bytes Payload* | 120 Bytes | 20 Bytes | 140 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *PSH/ACK* *50 Bytes Payload* | 70 Bytes | 20 Bytes | 90 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | **Connection Shutdown** | **80 Bytes** | **80 Bytes** | **160 Bytes** | | *FIN/ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *FIN/ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | *ACK* | 20 Bytes | 20 Bytes | 40 Bytes | | **Total Sum** | **374 Bytes** | **220 Byte** | **594 Bytes** | ### User Datagram Protocol (UDP) In comparison to the TCP header (20 bytes), the UDP header with only 8 bytes is more lightweight. Furthermore, UDP does not rely on the 3-way handshake and acknowledging individual data packets. This makes it a bit more unreliable but can save a lot of transmitted data in suitable applications. The use case shown in the calculation is the same as for the TCP example. A payload of 100 bytes of data from a device towards a UDP server. Afterward, 50 bytes are returned from the server towards the device. | Description | UDP Packets | IP Packets | Data Volume Sum | | --- | --- | --- | --- | | **Payload Exchange** | **166** | **40** | **206** | | *Device to Server* *100 Bytes Payload* | 108 | 20 | 128 | | *Server to Device* *50 Bytes Payload* | 58 | 20 | 78 | | **Total Sum** | **166** | **40** | **206** | --- # Features & Limitations Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-data-services/data-services-features-limitations/ # Features ## Service Availability The data service is available with all 1NCE SIMs using the Radio Access Technologies (RAT) 2G, 3G, 4G, LTE Cat-M and NB-IoT. The local availability depends on the coverage of the 1NCE roaming partners. Not all RAT are provided in each country. ## Data Bandwidth Throughput While most IoT applications might only have low bandwidth and not very strict latency requirements, other use cases might require high bandwidth with low latency. The 1NCE Data Service offers a maximum guaranteed data throughput of one megabit per second (**1 MBit/s**). Please note that the achievable throughput and latency are dependent on the used RAT, device specifications, and environmental factors (e.g., location, signal reception, etc.). ## SIM - IP Address * Each customer gets personal, private Internet Protocol (IP) ranges assigned for their SIM cards. * 1NCE uses addresses from the private IP space (RFC 1597) which are not allocated in the public internet and thus can be used freely in private networks. * All SIM cards assigned will have an IP address of one or more dedicated IP address spaces. * Usually, /24 address spaces will be used where in total 254 SIM cards can be fitted into. It is possible that /16 IP spaces with 65.536 individual SIM addresses might be used in newer organizations. * Additional IP space(s) will be assigned automatically. * SIMs will be assigned randomly to the IP space(s) of the given organization. * SIM IP address will be static as long as the SIM is not transferred between (sub-)organizations. A transfer will cause a change in IP address. * It is possible that a SIM card can get assigned a x.x.x.0 IP address. * The IP address spaces assigned to your account can be verified in the 1NCE Portal. > 📘 SIM IP Spaces Changes > > Please note that the pool of general SIM IP Spaces might be altered and new spaces might be added later on to increase overall capacity. ## SIM - IP Spaces All 1NCE SIMs are assigned IP Addresses from the following general IP Spaces. The IP Spaces assigned to customers will originate from these larger spaces. It is important to keep track of these spaces especially for VPN, IP Sec and VPN Peering setups. * 100.64.0.0/10 * 10.21.0.0/16 * 10.22.0.0/15 * 10.24.0.0/14 * 10.32.0.0/12 * 10.52.0.0/14 * 10.56.0.0/14 * 10.129.0.0/16 * 10.130.0.0/15 * 10.132.0.0/14 * 10.137.0.0/16 * 10.138.0.0/15 * 10.140.0.0/14 * 10.144.0.0/13 * 10.152.0.0/14 * 10.156.0.0/15 * 10.160.0.0/11 * 10.192.0.0/10 * 10.240.0.0/13 * 10.248.0.0/13 ## Network Translation and 1NCE VPN The infrastructure of the 1NCE Data Service network uses Network Address Translation (NAT) to route traffic from each connected SIM device to the public internet. For providing a private, more secure connectivity, as the devices are not directly exposed to the public internet. This also implies that a connection establishment from an application on the internet towards a 1NCE SIM is not directly possible without using the 1NCE VPN Service. On the other hand, target locations in the public internet space can be reached from any device with a 1NCE SIM. The traffic from each device is routed via the 1NCE Internet Breakout. For more details review the 1NCE Network Services, [Internet Breakout](/docs/network-services/network-services-internet-breakout) and [VPN Service](/docs/network-services/network-services-vpn-service/). > 📘 Data Connection Establishment > > When using the default Internet Breakout, the SIM device has to establish the Data Connection towards the targeted internet service. Due to the NAT Gateway, individual SIMs are not reachable from the open internet. The sequence diagram below shows the flow of a SIM device using the NAT Internet Breakout to establish a connection to a public internet server/service. The connection establishment always needs to come from the SIM device. After a connection session (e.g., TCP session) was opened by the SIM device, bidirectional communication is possible.
![Schematic sequence diagram of a data session establishment.](/img/connectivity-services/connectivity-services-data-services/data-services-features-limitations/001.png)
The second sequence diagram below shows the possible data service when using the 1NCE VPN Service. This free to use service allows to directly connect to the 1NCE Network to access/connect SIM devices from the customer server side. Please note that only traffic from the SIM device with the VPN client IP address as destination will be routed towards the connected VPN client. All other traffic from the SIM device will be routed through the Internet Breakout. For more details, please see the VPN Service chapter.
![Schematic sequence diagram of a data session establishment using the 1NCE VPN service.](/img/connectivity-services/connectivity-services-data-services/data-services-features-limitations/002.png)
## Data Protocols The concept of the Open Systems Interconnection model applies to the 1NCE Data Service structure. The GPRS Tunneling Protocol (GTP) is used on layer 3 to transfer user application data between the device with a 1NCE SIM and the internet or application server and vice versa. All the data traffic is wrapped in the GTP, on top of this protocol (layer 4+) the customer is free to use any transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port assignment. ## Domain Name System (DNS) The Domain Name System (DNS) is used to resolve Uniform Resource Locators (URL) to an addressable IP. When using the 1NCE Internet Breakout, the public IP `8.8.8.8` is served as primary and `8.8.4.4` as secondary default Domain Name Server. Some devices have issues with obtaining the DNS served by the network. A manual configuration of a DNS is sometimes advisable. On some NB-IoT U-Blox devices used in Europe, MNO profile 101 has to be used rather than MNO profile 100 to obtain the DNS served by the network. *** # Limitations ## Maximum Transmission Unit (MTU) Size The Maximum Transmission Unit (MTU) is the size of the largest IP packet (layer 4) possible which can be transferred in a respective frame on layer 3 without the need for fragmentation in the packed based core network. If a send packet is larger than the specified MTU, the packet needs to be fragmented, thus creating more overhead and delays. Theoretically, a size of 1500 bytes is possible with the 1NCE Data Service. Based on prior experience with IoT devices and mobile networks, it is recommended to keep the **MTU size lower than about 1200 bytes**. ## Data Volume Usage Based on the customer specific tariff of a 1NCE SIM, a certain data volume is included. The available volume and current usage can be inquired in the 1NCE Portal or through the [1NCE API](/api/). The data volume can be used freely. If the volume runs out or customer-set threshold is reached, the Data Service for a SIM card is blocked. No new data sessions (PDP Context) can be initialized. The device can still attach to the mobile network and use the other services but is not able to re-create a new PDP Context. Moreover, any existing data session is terminated if the volume limit is reached. If the restricted SIM is topped up with new data volume, the blocking will be reset and new data sessions can be established. If a SIM runs out of data volume, the device **should restrict the attempts to create new (failed) PDP sessions** as the reject response can lead to the device spamming the network with session requests. Please note that the customer is responsible for implementing a back off timer for this edge case behavior. {/* ## Internet Breakout Timeout > ❗️ > > **This does only apply to connections made through the 1NCE Internet Breakout and NOT the 1NCE VPN Service!** Devices using the 1NCE Internet Breakout are placed behind a NAT gateway. After 350 seconds of no packets being transmitted, a established connection via the 1NCE Internet Breakout will be closed automatically. To keep the connection alive within 350 seconds a IoT device must send a keep-alive packet at least once in the 350-second timeframe. Otherwise, the 1NCE SIM device must re-establish the connection after this timeout. */} ## 1NCE Breakout IP Blacklisting The traffic from all 1NCE SIMs towards the public internet is routed through a NAT with a couple of public-facing IP addresses. These public breakout IPs are listed in the 1NCE Portal. All requests towards public internet services appear to come from only these few IPS. Most public services and APIs apply a request limit and smart filtering to detect and filter out denial of service (DDoS) and similar attacks. Very frequent queries (e.g., every second) from multiple SIMs towards one endpoint could trigger these filtering mechanisms. This will result in the public service blocking requests from 1NCE SIM devices, rendering the service unusable. Most public services cannot differentiate between individual SIMs due to the 1NCE NAT network structure. It is strongly recommended to program devices with 1NCE SIMs in a way that they do not aggressively query such shared resources. ## Device to Device Communication The peer to peer communication between two or multiple SIMs is not possible. This rules is the same for SIMs of one customer or between different customers. There is no direct routing of IP traffic between SIMs possible. To exchange specific data packages between SIM devices, an application server is needed. This application server is ideally connected via the 1NCE VPN Service. Thus, it can receive data messages from one SIM device via the VPN client IP and redirect them to another SIM device in the same customer account by its static IP address. ## TCP/TLS with NB-IoT NB-IoT is great for getting coverage in hard-to-reach areas like basements or countryside. It comes with the disadvantage of higher transmission latency as the radio device repeats transmissions multiple times to allow the receiving cell tower to capture the data accurately. In total, it can add up to an expected latency between 1 and 10 seconds. Compared to the latency of normal LTE or CAT-M of 10 to 100 milliseconds, NB-IoT latency is very high. Due to the high latency, it is not advised to use TCP based protocols for data transmission. These protocols expect lower latency. TCP based protocols can work over NB-IoT in ideal conditions but if the latency increases due to environment changes or radio changes, TCP will start sending retransmissions and the connectivity will start to break. 1NCE recommends using only UDP based protocols like CoAP or LwM2M for NB-IoT radio access type. The feature set of these specialized protocols closely match TCP behavior with the added benefit of being more robust in high latency transmissions. Please avoid using TCP based protocols on NB-IoT radio interfaces. {/* ## PDP Data Session Retention7 days1kb of dataotherwise dropped */} --- # Mobile Network Services Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-mobile-network-services/
![Schematic overview of the 1NCE network structure.](/img/connectivity-services/connectivity-services-mobile-network-services/001.png)
1NCE is not just another Internet of Things (IoT) Mobile Virtual Network Operator (MVNO). In a unique way, 1NCE enhances the capabilities of a full MVNO with the power and quality of Tier-1 mobile networks. Our network capabilities exceed those of traditional MVNOs because we have a direct interface to Radio Access Networks of Tier-1 operators which enable us to control and manage the IoT traffic directly and more eminently. Additionally, we utilize essential network assets of our Mobile Network Operator (MNO) roaming partners to guarantee long-term stability and security of our network services to customers. The Network of 1NCE comprises of both a lean virtualized and a cloud based core network as well as a streamlined and full-automatized business support system. All included network elements as well as the feature set of the platform have been developed with a clear focus on IoT. All functions and features are fully automatized for maximum scale and ease of use. The Mobile Network Services chapters focus on all features and parts around the general mobile network connectivity. --- # 1NCE IoT Network Coverage Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-coverage/
![world_coverage_en_03-2022.png](/img/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-coverage/48a9e97-world_coverage_en_03-2022.png)
The country and region coverage of 1NCE is growing steadily and rapidly. 1NCE already offers radio services through roaming partners in over 100 countries and regions in Europe (including UK), Asia, North America, South America, Africa and Oceania. The 1NCE IoT SIM card can be used in these regions without additional costs. 1NCE supports all radio standards such as 2G, 3G, 4G/LTE-M as well as NB-IoT in selected countries and regions. 1NCE strives to continuously enhance the outreach and coverage of the IoT network. If there is a specific need for a radio access technology in a particular area, please check the Coverage Map to see if the actual service is available or reach out to the 1NCE Support. # GSMA Coverage Estimation Map The GSM Association (GSMA) provides Network Coverage Maps which show the theoretical coverage of mobile network operators for the different radio access technologies. Important to note is that their maps are calculated and are only a rough estimation. The shown values can deviate from the real coverage quite a bit. For 4G/LTE and especially for the optimized RAT LTE Cat M and NB-IoT, the shown coverage is often depicted worse than it actually is.\ Please note that the GSMA maps are a general coverage tool and do not reflect list complete list of the 1NCE Coverage Map. --- # 2G/3G Discontinuation Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-mobile-network-services/mobile-network-services-discontinuation/ From the physical side, the radio frequency spectrum used for wireless communication is a very sparse, limited but valuable resource. Each country/region through the world uses and optimizes this common spectrum differently, but the same physical limitations apply.\ As new, more advanced, and powerful mobile radio network technologies emerge, older standards make way for future deployments. Current mobile Radio Access Technologies (RAT) range from 2G (GSM), 3G (UMTS), 4G (LTE) including NB-IoT and LTE Cat-M to the most recent fifth generation 5G. The advancements in 4G and 5G provide simpler, scalable network structures and are more optimized for IoT and future-driven use cases compared to 2G and 3G. As a result, many Mobile Network Operators (MNO) decided to discontinue 2G and/or 3G to make space in the radio frequency bands for 4G and 5G deployments. # Migrating to Future-Proof Technologies Early on mobile IoT device integrations used 2G/3G RATs as primary network resource. Today, many deployed IoT devices still use older RATs as fallback solution as new radio standards (e.g., NB-IoT and LTE-M/Cat-M) start to be deployed. This is backed by the usage statistics we see in the 1NCE Network. While in the European Region 2G still is the dominating standard for IoT applications, the adaption and demand for 4G/LTE with NB-IoT and LTE Cat-M is increasing significantly as availably of affordable modem hardware and international network coverage grows. As most IoT device integrations aim for long-term deployment, device developers and manufactures need to be on the lookout for ongoing radio resource reallocations in mobile networks. It is all about choosing the right radio technology for future usage. From the SIM card perspective, the 1NCE SIM cards support all Radio Access Technologies (2G, 3G, 4G, Cat-M and NB-IoT). To future-prove IoT hardware devices, 1NCE recommends the usage of 4G and the related LTE Cat-M and NB-IoT modem hardware wherever it is possible. 2G and 3G are good alternatives to use for providing a fallback in case of a 4G outage but should ideally not be considered main point of future IoT connectivity. # Upcoming 2G (GSM) & 3G (UMTS) Discontinuations Different countries and regions follow different shutdown/sunset/discontinuation patterns when it comes to mobile radio networks. In European Region, mostly 3G (UMTS) services are shut down and 2G (GSM) radio coverage is preserved due to fallback and emergency service use cases. In the US, Asia and Australia, the focus on freeing up radio resources lies on 2G (GSM) network resources. As 1NCE IoT SIM connectivity relies on their roaming partners for local radio coverage, the overall coverage and available Radio Access Technologies are impacted by the local shutdowns. The list below provides an overview of upcoming changes due to discontinuations in the 1NCE Coverage. | Country/Region | Network Operator | Also known as | 2G (GSM) | 3G (UMTS) | | :--- | :--- | :--- | :--- | :--- | | Albania | Vodafone Albania | \- | \- | Completed | | Andorra | Andorra Telecom S.A.U. | \- | \- | 01.09.2026 | | Anguilla | Cable & Wireless (West Indies) Ltd. Anguilla (Flow) | \- | Completed | \- | | Anguilla | Digicel (Jamaica) Limited | \- | Completed | \- | | Antigua & Barbuda | Cable & Wireless (Anguilla) Limited | \- | Completed | \- | | Antigua & Barbuda | Digicel (Jamaica) Limited | \- | Completed | \- | | Argentina | Telenet Group BVBA/SPRL | \- | \- | Completed | | Aruba | Digicel (Jamaica) Limited | \- | Completed | \- | | Aruba | SETAR (Servicio di Telecomunicacion di Aruba) | \- | 01.08.2026 | \- | | Australia | Optus Mobile Pty Ltd | \- | Completed | \- | | Australia | Telstra Cooperation Ltd | \- | Completed | \- | | Austria | A1 Telekom Austria AG | \- | 31.05.2028 | Completed | | Austria | Hutchison 3 Austria GmbH | \- | \- | Completed | | Bahrain | STC Bahrain B.S.C Closed | \- | \- | Completed | | Bahrain | Zain Bahrain B.S.C | \- | \- | Completed | | Bangladesh | Grammenphone Ltd. | \- | \- | Completed | | Barbados | Cable & Wireless Barbados Ltd. | \- | Completed | \- | | Barbados | Digicel (Jamaica) Limited | \- | Completed | \- | | Belgium | Orange Belgium NV/SA | \- | 31.12.2028 | Completed | | Belgium | Telenet Group BVBA/SPRL | \- | 31.12.2027 | Completed | | Bermuda | Digicel (Jamaica) Limited | \- | Completed | \- | | Bonaire (Netherlands Antilles) | Curacao Telecom N.V. | \- | 30.11.2026 | 31.03.2028 | | British Virgin Islands | Cable & Wireless West Indies | \- | Completed | \- | | British Virgin Islands | Digicel (Jamaica) Limited | \- | Completed | \- | | Bulgaria | A1 Bulgaria | \- | \- | Completed | | Canada | Bell Mobility Inc. | \- | \- | 01.03.2027 | | Canada | SaskTel | \- | Completed | 01.10.2027 | | Canada | TELUS Communications Canada Inc. | \- | Completed | \- | | Cayman | Cable & Wireless West Indies | \- | Completed | \- | | Cayman | Digicel (Jamaica) Limited | \- | Completed | \- | | China | China Mobile International Limited | \- | 23.06.2026 | Completed | | China | China Unicom | \- | Completed | 30.06.2026 | | Colombia | Colombia Movil S.A. | \- | Completed | \- | | Colombia | Comunicacion Celular S.A. (Claro) | \- | Completed | \- | | Costa Rica | I.C.E. (Instituto Costarricense de Electricidad) | \- | Completed | \- | | Costa Rica | LIBERTY TELECOMUNICACIONES DE COSTA RICA LY | \- | Completed | \- | | Croatia | A1 Hrvatska d.o.o. | \- | \- | Completed | | Croatia | Croatian Telecom Inc. | \- | \- | Completed | | Curacao (Netherlands Antilles) | Curacao Telecom N.V. | \- | 30.11.2026 | 31.03.2028 | | Cyprus | Cyprus Telecommunications Authority (Cyta) | \- | \- | 31.12.2027 | | Czech Republic | O2 Czech Republic, a.s. | \- | \- | Completed | | Czech Republic | T-Mobile Czech Republic | \- | 01.01.2028 | Completed | | Czech Republic | Vodafone Czech Republic | \- | Completed | Completed | | Denmark | Hi3G Denmark ApS | \- | \- | Completed | | Denmark | TDC NetCo | \- | \- | Completed | | Denmark | Telenor A/S | \- | \- | Completed | | Denmark | Telia Denmark ApS | \- | \- | Completed | | Dominica | Cable & Wireless Dominica Ltd. | \- | 30.08.2026 | \- | | Dominica | Digicel (Jamaica) Limited | \- | Completed | \- | | El Salvador | Telemovil EL Salvador S.A | \- | Completed | \- | | Estonia | Elisa Eesti AS | \- | 31.12.2029 | \- | | Estonia | Tele2 Eesti AS | \- | \- | Completed | | Estonia | Telia Eesti | \- | 31.12.2029 | \- | | Finland | Alands Telekommunikation Ab | \- | Completed | \- | | Finland | DNA Ltd | \- | 31.12.2029 | \- | | Finland | Elisa Corporation | \- | \- | Completed | | Finland | Telia Finland Oyj | \- | \- | Completed | | France | Bouygues Telecom France | \- | 31.12.2026 | 31.12.2029 | | France | Orange France | \- | 31.12.2026 | 31.12.2028 | | France | SFR France | \- | 31.12.2026 | 31.12.2028 | | French Guiana | Digicel Antilles Française | \- | Completed | \- | | French Guiana | Orange Caraibe | \- | Completed | 31.12.2028 | | Germany | Deutsche Telekom | \- | 30.06.2028 | Completed | | Germany | O2 / Telefónica Germany GmbH & Co. OHG | \- | \- | Completed | | Germany | O2 / Telefónica Germany GmbH & Co. OHG | \- | \- | Completed | | Germany | Vodafone | \- | 31.12.2030 | 31.12.2030 | | Great Britain | EE | \- | \- | Completed | | Great Britain | EE Limited | \- | \- | Completed | | Great Britain | Hutchison 3G UK Ltd | \- | \- | Completed | | Great Britain | O2/Telefonica UK Limited | \- | Start summer 2029 | Completed | | Great Britain | Vodafone UK Limited | \- | 31.12.2030 | Completed | | Greece | COSMOTE Mobile Telecommunications S.A | \- | \- | Completed | | Greece | Vodafone Roaming Services S.A.R.L. | \- | \- | Completed | | Greece | WIND HELLAS Telecommunications S.A | \- | \- | Completed | | Greenland | Tele Greenland A/S | \- | \- | Completed | | Grenada | Cable & Wireless Grenada Ltd. | \- | Completed | \- | | Grenada | Digicel (Jamaica) Limited | \- | Completed | \- | | Guadeloupe (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Guadeloupe (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Guam | PTI Pacifica Inc. dba IT&E | \- | \- | Completed | | Guernsey | JT (Jersey) Limited | \- | \- | Completed | | Haiti | Digicel (Jamaica) Limited | \- | Completed | \- | | Hong Kong | Hong Kong Telecommunications (HKT/CSL) Limited (PCCW) | \- | Completed | \- | | Hong Kong | Hutchison Telecommunications Hong Kong Holdings Limited | \- | Completed | 31.10.2026 | | Hong Kong | SmarTone | \- | Completed | 30.09.2026 | | Hungary | Magyar Telekom Plc. | \- | \- | Completed | | Hungary | Yettel Magyarország | \- | \- | Completed | | Iceland | Nova Island | \- | \- | Completed | | Iceland | Síminn hf | \- | Completed | Completed | | Iceland | Sýn hf. (Vodafone) | \- | Completed | \- | | India | Airtel Andhra Pradesh | \- | \- | Completed | | India | Airtel Assam | \- | \- | Completed | | India | Airtel Bihar | \- | \- | Completed | | India | Airtel Chennai | \- | \- | Completed | | India | Airtel Delhi | \- | \- | Completed | | India | Airtel Gujarat | \- | \- | Completed | | India | Airtel Haryana | \- | \- | Completed | | India | Airtel Himachal Pradesh | \- | \- | Completed | | India | Airtel Karnataka | \- | \- | Completed | | India | Airtel Kerala | \- | \- | Completed | | India | Airtel Kolkata | \- | \- | Completed | | India | Airtel Madhya Pradesh | \- | \- | Completed | | India | Airtel Maharashtra & Goa | \- | \- | Completed | | India | Airtel Mumbai | \- | \- | Completed | | India | Airtel North East | \- | \- | Completed | | India | Airtel Orissa | \- | \- | Completed | | India | Airtel Punjab | \- | \- | Completed | | India | Airtel Rajasthan | \- | \- | Completed | | India | Airtel Tamilnadu | \- | \- | Completed | | India | Airtel UP East | \- | \- | Completed | | India | Airtel Uttar Pradesh West | \- | \- | Completed | | India | Airtel West Bengal | \- | \- | Completed | | Indonesia | PT Indosat Tbk (Indosat Ooredoo) | \- | \- | Completed | | Indonesia | PT. XL Axiata Tbk | \- | \- | Completed | | Israel | Hot Mobile Ltd. | \- | Completed | Completed | | Israel | Partner Communications Company Ltd. | \- | Completed | Completed | | Israel | Pelephone Communications Ltd. | \- | Completed | Completed | | Italy | Telecom Italia SpA | \- | 31.12.2029 | Completed | | Italy | Vodafone Italy | \- | \- | Completed | | Italy | Wind Tre S.p.A. | \- | \- | Completed | | Jamaica | Cable & Wireless Jamaica Limited | \- | Completed | \- | | Jamaica | Digicel (Jamaica) Limited | \- | Completed | \- | | Japan | KDDI | \- | Completed | Completed | | Japan | NTT DoCoMo | \- | Completed | Completed | | Japan | Softbank KK | \- | Completed | \- | | Jersey | JT (Jersey) Limited | \- | \- | Completed | | Jordan | Umniah Mobile Company | \- | Completed | \- | | Korea, Republic of | KT Corporation | \- | Completed | \- | | Korea, Republic of | LG Uplus Corporation | \- | Completed | \- | | Korea, Republic of | SK Telecom | \- | Completed | \- | | Kosovo | IPKO Telecommunications LLC | \- | \- | Completed | | Kuwait | National Mobile Telecommunications Company (K.S.C) | \- | \- | Completed | | La Désirade (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Latvia | Latvijas Mobilais Telefons SIA | \- | \- | Completed | | Latvia | SIA Bite Mobile | \- | \- | Completed | | Latvia | TELE2 Latvia | \- | \- | Completed | | Les Saintes (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Liechtenstein | Telecom Liechtenstein AG | \- | Completed | Completed | | Lithuania | Telia Lietuva, AB | \- | 31.12.2028 | Completed | | Lithuania | UAB Bite Lietuva | \- | 31.12.2028 | Completed | | Luxembourg | Orange Luxembourg | \- | 31.12.2030 | Completed | | Luxembourg | Post Luxembourg | \- | 31.12.2026 | Completed | | Luxembourg | Tango SA | \- | \- | Completed | | Macau | Companhia de Telecomunicações de Macau, S.A.R.L. | \- | Completed | Completed | | Macedonia, North | Makedonski Telekom AD Skopje | \- | \- | Completed | | Malaysia | Digi Telecommunications Sdn Bhd | \- | \- | Completed | | Malaysia | Maxis Broadband Sdn. Bhd. | \- | \- | Completed | | Mariana Islands | PTI Pacifica Inc. dba IT&E | \- | \- | Completed | | Marie Galante (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Marie Galante (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Martinique (French Antilles) | Digicel Antilles Française | \- | Completed | \- | | Martinique (French Antilles) | Orange Caraibe | \- | Completed | 31.12.2028 | | Mayotte | Orange Reunion | \- | Completed | \- | | Mexico | AT&T Comercialization Mexico | \- | Completed | \- | | Montenegro | CRNOGORSKI TELEKOM A.D. | \- | \- | Completed | | Montenegro | MTEL d.o.o. Podgorica | \- | Completed | \- | | Montserrat | Digicel (Jamaica) Limited | \- | Completed | \- | | Nepal | Ncell Axiata Limited | \- | \- | From July 2026 | | Nepal | Nepal Doorsanchar Company | \- | Completed | \- | | Netherlands | KPN B.V. | \- | 01.12.2027 | Completed | | Netherlands | T-Mobile Netherlands | \- | Completed | \- | | Netherlands | Vodafone Libertel N.V. | \- | 31.12.2026 | Completed | | New Caledonia | Office des Postes et Telecommunications | \- | Completed | \- | | New Zealand | Spark New Zealand Trading Limited | \- | Completed | Completed | | New Zealand | Two Degrees Networks Limited | \- | Completed | Completed | | Norway | Telenor Norge AS | \- | 31.12.2027 | Completed | | Norway | Telia Norge AS | \- | Completed | Completed | | Oman, Sultanate of | Oman Telecommunications Company S.A.O.G. | \- | \- | Completed | | Oman, Sultanate of | Omani Qatari Telecommunications Company | \- | \- | Completed | | Philippines | Smart Communications, Inc. | \- | \- | 31.12.2026 | | Poland | Orange Polska S.A. | \- | 31.12.2030 | Completed | | Poland | T-Mobile Polska S.A. | \- | 31.12.2030 | Completed | | Puerto Rico | AT&T USA | \- | Completed | \- | | Puerto Rico | T-Mobile USA | \- | \- | Completed | | Qatar | Ooredoo QSC | \- | \- | Completed | | Qatar | Vodafone | \- | \- | Completed | | Reunion | Orange Reunion | \- | Completed | \- | | Romania | Orange Romania | \- | 31.12.2030 | Completed | | Romania | Telekom Romania Mobile Communications S.A. | \- | \- | Completed | | Romania | Vodafone Romania S.A. | \- | Completed | \- | | Saint Barthelemy | Digicel Antilles Française | \- | Completed | \- | | Saint Barthelemy | Orange Caraibe | \- | Completed | 31.12.2028 | | Saint Kitts & Nevis | Digicel (Jamaica) Limited | \- | Completed | \- | | Saint Lucia | Digicel (Jamaica) Limited | \- | Completed | \- | | Saint Martin (French part) | Digicel Antilles Française | \- | Completed | \- | | Saint Martin (French part) | Orange Caraibe | \- | Completed | 31.12.2028 | | Saint Vincent and Grenadines | Digicel (Jamaica) Limited | \- | Completed | \- | | Saudi Arabia | Saudi Telecom Company (STC) | \- | \- | Completed | | Serbia | A1 Serbia | VIP Mobile | \- | Completed | | Singapore | SIMBA | \- | Completed | \- | | Singapore | SingTel Mobile | \- | Completed | Completed | | Singapore | StarHub Mobile Pte Ltd | \- | Completed | Completed | | Sint Maarten (Netherlands Antilles) | Telcell N.V. | \- | Completed | \- | | Slovak Republic | O2 Slovakia, s.r.o. | \- | \- | Completed | | Slovak Republic | Orange Slovensko A.S | \- | 31.12.2030 | Completed | | Slovak Republic | Slovak Telekom, a.s. | \- | \- | Completed | | Slovenia | A1 Slovenija d.d. | \- | 31.12.2030 | Completed | | Slovenia | Telekom Slovenije d.d. | \- | \- | Completed | | South Africa | MTN South Africa | \- | 31.12.2027 | 31.12.2027 | | South Africa | Telkom South Africa | \- | 31.12.2027 | 31.12.2027 | | South Africa | Vodacom South Africa | \- | 31.12.2027 | 31.12.2027 | | Spain | Orange Espagne S.A.U. | \- | 31.12.2030 | 31.12.2027 | | Sri Lanka | Dialog Axiata PLC | \- | \- | Completed | | Sri Lanka | Mobitel (Pvt) Limited | \- | \- | Completed | | Suriname | Digicel Suriname N.V. | \- | Completed | 31.03.2029 | | Sweden | Hi3G Access AB | \- | \- | Completed | | Sweden | Tele2 AB Sweden | \- | Completed | Completed | | Sweden | Telenor Sverige AB | \- | Completed | Completed | | Sweden | Telia Sverige AB | \- | 31.12.2027 | Completed | | Switzerland | Salt Mobile SA (formerly Orange) | \- | Completed | \- | | Switzerland | Sunrise, Switzerland | \- | Completed | Completed | | Switzerland | Swisscom Mobile Ltd. | \- | Completed | Completed | | Taiwan | Chungwa Telecom LDM Taiwan | \- | Completed | Completed | | Taiwan | Far Eastone Taiwan | \- | Completed | Completed | | Taiwan | Taiwan Mobile Co., Ltd. | \- | Completed | Completed | | Taiwan | Taiwan Star Telecom Corporation Limited | \- | Completed | Completed | | Tanzania | Viettel Tanzania Limited | \- | 30.09.2026 | Completed | | Thailand | Advanced Wireless Network Company (AIS) | \- | 30.09.2026 | 30.09.2026 | | Thailand | True Move Company Ltd. | \- | Completed | \- | | Thailand | True Move H Universal Communication | \- | Completed | \- | | Trinidad and Tobago | Digicel Trinidad and Tobago Ltd | \- | Completed | 31.03.2029 | | Tunisia | Ooredoo Tunisie SA | \- | \- | 30.06.2026 | | Tunisia | Orange Tunisie, SA | \- | \- | 30.06.2026 | | Tunisia | Tunisie Telecom | \- | \- | 30.06.2026 | | US Virgin Islands | AT&T USA | \- | Completed | \- | | US Virgin Islands | T-Mobile USA | \- | \- | Completed | | USA | AT&T USA | \- | Completed | \- | | USA | Cellular One (Smith Bagley, Inc.) | \- | Completed | Completed | | USA | NE Colorado Cellular, Inc | \- | Completed | \- | | USA | T-Mobile USA | \- | \- | Completed | | USA | Union Telephone Company | \- | \- | Completed | | Ukraine | Kyivstar JSC | \- | \- | 31.12.2030 | | Ukraine | Lifecell LLC | \- | \- | 31.12.2030 | | Ukraine | Vodafone | \- | \- | 31.12.2030 | | United Arab Emirates | DU | \- | Completed | \- | | Venezuela | Corporacion Digitel C.A. | \- | Completed | \- | | Venezuela | Digitel Venezuela | \- | Completed | \- | | Vietnam | MobiFone Corporation | \- | 30.09.2026 | 30.09.2028 | | Vietnam | VNPT International | \- | 30.09.2026 | 30.09.2028 | | Vietnam | Viettel Group | \- | 30.09.2026 | Completed | Table Version 01.07.2026 Please review the 1NCE Coverage Map to get an up-to-date view of the available country and access technology coverage. --- # No Harm to Network Guidelines Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-no-harm-network/ To ensure reliable availability of all devices connected in the Internet of Things, network providers put in a lot of technological and human effort around the clock. But IoT developers can also contribute a lot to the efficiency and reliability of their IoT devices and platforms. We have compiled the top 5 for secure and long-term operation of IoT devices in the Internet of Things: ## 1. Avoid Synchronized Behavior IoT devices should never contact their platform at the same time to avoid congestion. ## 2. Reduce Connection Setup Avoid unnecessary connection setup and disconnection of devices. This saves energy and reduces the load on servers and networks. ## 3. Aggregate, Compress, Encode Data If you transfer your data in an optimized way, you extend the battery life of your devices. ## 4. Suitable Energy-Saving Modes Depending on the application, energy can be saved in different ways at the network and application level. ## 5. Always Diagnose Before Restarting Always identify errors before restarting devices. *** This IoT Solution Guideline summarizes the "No Harm to Network" requirements from 1NCE GmbH originating in GSMA TS.34 v5.0, IoT Device Connection Efficiency Guidelines 1, use-cases or features not covered yet within GSMA TS.34, as well as lessons learned gained from IoT commercial deployments. The requirements including the words **"SHALL"** or **"SHALL NOT"** in their descriptions are mandatory and all guidelines with **"SHOULD"** or **"SHOULD NOT"** are recommended. These guidelines are divided into three sections, reflecting how IoT Service Providers are required to implement "No Harm to Network" considerations and best-practice design in the different IoT Solution Layers (refer to Figure 1).
![iot_guidelines.jpg](/img/connectivity-services/connectivity-services-no-harm-network/956b1b9-iot_guidelines.jpg)
*** # Definitions ## IoT Service Provider Companies offering IoT Services to end consumers or enterprises via the 1NCE GmbH Connectivity Layer (3GPPTM mobile networks). ## IoT Service Application Business application logic of the IoT Service which processes the data collected from assets. The IoT Service Provider hosts their IoT Service Application on a server or Cloud Platform provided by 1NCE GmbH or another third party. ## Cloud Platform Infrastructure used by the IoT Service Provider to host IoT Services, manage IoT Devices and exchange data with their IoT Devices over the 1NCE GmbH Connectivity Layer. The Cloud Platform may host the IoT Server Application logic and includes Service Enablement functions. Generally, this is referred to as the "IoT Service Platform" in this document. ## Service Enablement Core service functions such as device management, discovery, registration, group management, application and service management, communication management, data management, service charging and accounting, as well as subscription and notification, are common needs across the wide spectrum of IoT solutions. These aspects are typically coordinated between IoT Devices and the IoT Service Platform on this logical layer. Server-side, service enablement may be handled by an independent orchestrator or connector acting as an endpoint for all communication to/from the IoT Devices. Such a connector may be placed in front of one or several clouds hosting IoT Server Applications. The provider of the Service Enablement may be a Mobile (Virtual) Network Operator, or the developer of the IoT Device and Server Applications. ## IoT Device Sensors, actuators, or other deployed Machine to Machine (M2M) hardware exchanging data bidirectionally and managed by the IoT Service Provider over the Application, Service Enablement and Connectivity Layers. The communication between IoT Device and IoT Service Provider is referred to as the IoT Service. ## IoT Device Application The application logic running on the IoT Device microcontroller (MCU) and exchanging data with the IoT Service Platform. It sends AT commands to the IoT Device integrated communication module/chipset in order to access the 1NCE GmbH Connectivity Layer. *** # IoT Service Provider Guidelines ## Avoidance of Synchronized Behavior Any IoT Service Platform or IoT Service Application which communicates to multiple IoT Devices **SHALL** avoid timely synchronized behavior and employ a randomized pattern for accessing IoT Devices registered to the platforms domain. The triggering of data transmissions, the rebooting of the IoT Device hardware or subcomponents (such as the communication module/chipset), or the issuing device management commands (including, but not limited to (re-) registrations and firmware updates) **SHALL NOT** be timely synchronized. ## IoT Service Platform or IoT Service Application Temporarily Offline Recovery If the IoT Service Platform or IoT Service Application are temporarily offline, they **SHALL NOT** request the IoT Devices to synchronize all at once when coming back online. ## Triggering Devices only when Attached The IoT Service Platform or IoT Service Application **SHALL** be aware of the IoT Device state and only send "wake up" triggers whenever the IoT Device is known to be attached to the mobile network. ## Behavior when IoT Device does not Respond to SMS Triggers If the IoT Service Platform or IoT Service Application uses SMS triggers to "wake up" IoT Devices, it **SHALL** avoid sending multiple SMS triggers when no response is received within a certain time period. Communication over a 3GPPTM NB-IoT access bearer **SHALL NOT** use SMS on 1NCE GmbH mobile network. ## Behavior when SIM Subscription is Inactive If the SIM subscription associated with an IoT Device is to be placed in a temporarily inactive state (i.e. for a fixed period of time), the IoT Service Provider **SHALL** first ensure that the IoT Device’s communication module/chipset is temporarily disabled to restrict it from trying to register to the mobile network once the SIM is disabled. ## Behavior when SIM Subscription is Permanently Disabled Before the SIM subscription associated with an IoT Device is to be placed in a permanently terminated state, the IoT Service Provider **SHALL** first ensure that the IoT Device’s communication module/chipset is permanently disabled to restrict it from trying to register to the mobile network once the SIM is disabled. The IoT Service Provider **SHOULD** consider avoiding mechanisms for the permanent termination of IoT Devices that are not easily serviceable, as it may require manual intervention (i.e. a service call) to reenable the IoT Devices. ## Frequency and Prioritization of Data Transmissions Whenever there is a need to transmit data over the mobile network, the IoT Service Platform or IoT Service Application **SHOULD classify** the priority of each communication. The IoT Service Platform or IoT Service Application distinguishes between high-priority data requiring instantaneous transmission, versus delay tolerant or lower-priority data which can be aggregated and sent during non-peak hours.\ IoT Server Applications communicating with IoT Devices over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, SHALL optimize their application reporting period to never exceed 1NCE GmbH affiliate tariff daily maximum number of messages. ## Data Aggregation, Compression and Transcoding The IoT Server Application **SHALL** minimize the number of parallel mobile network connections and overall frequency of connections to IoT Devices over the mobile network. Data is aggregated by the IoT Server Application into an application report before being compressed and sent over the mobile network. Data transcoding and compression techniques are used, as per the IoT Service’s intended Quality of Service, to reduce connection attempts and data volumes.\ IoT Server Application using 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, SHALL optimize their payload sizes to comply with 1NCE GmbH affiliate monthly volume limits.\ IoT Service Provers SHALL NOT initialize significant numbers of IoT Devices (e.g. >100 units) communicating over 3GPPTM NB-IoT within one hour at the same location. *** # IoT Device Guidelines ## Avoidance of Synchronized Behavior The monolithic IoT Device Application **SHALL** avoid synchronized behavior with other IoT Devices or events, employing a randomized pattern (e.g. over a time period ranging from a few seconds to several hours, or days) to request a mobile network connection over the Connectivity Layer. The triggering of data transmissions, the rebooting of the IoT Device hardware or subcomponents (such as the communication module/chipset), or execution of device management commands (including, but not limited to (re-) registrations and firmware updates) **SHALL NOT** be synchronized. ## Use of "Always-On" Connectivity If the monolithic IoT Device Application sends data very frequently (i.e. inactivity periods shorter than two hours), it **SHALL** use a persistent PDP/PDN connection with the mobile network instead of activating and deactivating said connectivity. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. ## Handline of "Keep Alive" Messages on Home Network If the communication between the IoT Devices and mobile network is IP-based, it may require the use of TCP / UDP "keep alive" messages. In such cases, the IoT Device Application **SHALL** automatically detect the server-specific timers and/or mobile network firewall timers, such TCP\_IDLE value or UDP\_IDLE value (NAT timers as defined by 1NCE GmbH for consumer APN, or by business enterprise for own-administered NAT, in the case of private APN), when using push services. This is achieved by increasing the polling interval dynamically until a mobile network timeout occurs, and then operating just below the timeout value.\ IoT Device Applications communicating with the IoT Server Application over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHOULD NOT** implement TCP / UDP “keep alive” messages on the home network. In IoT Devices, the embedded Service Enablement Layer **SHOULD** implement this requirement in the same way as for IoT Device Applications. ## Data Aggregation, Compression and Transcoding The monolithic IoT Device Application SHALL minimize the number of parallel mobile network connections and overall frequency of connections between the IoT Device and the mobile network. Data is aggregated by the IoT Device Application into an application report before being compressed and sent over the mobile network. Data transcoding and compression techniques are used, as per the IoT Service intended Quality of Service, to reduce connection attempts and data volumes. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement.\ The IoT Device Application **SHOULD** monitor the volume of data it sends and receives over a defined time period. If the volume of data will soon exceed a maximum value defined by the IoT Service Provider (see Suggested Limits), the IoT Device Application sends a report to the IoT Service Platform and stops the regular sending of data until the necessary time period has expired. ## Frequency and Prioritization of Data Transmissions The IoT Device Application **SHOULD** monitor the number of network connections it attempts over a set time period. If the number of connection attempts exceeds a maximum value set by the IoT Service Provider (see Suggested Limits), the IoT Device Application sends a report to the IoT Service Platform and stops requesting mobile network connectivity until the necessary time period has expired. In tiered IoT Devices, the embedded Service Enablement Layer **SHOULD** comply to this requirement.\ IoT Devices Applications communicating with IoT Server Applications over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHALL** optimize their application reporting period to never exceed the IoT Service Provider daily maximum number of messages (see Suggested Limits). ## Localized Communication The IoT Device Application **SHALL** minimize any geographical network loading problems. There **SHALL** be no coordination of all IoT Devices in a given region of the IoT Service to undergo like-operations producing network loading, e.g. firmware updates. ## Adaption to Mobile Network Capabilities, Data Speed and Latency The IoT Device Application **SHALL** be capable of adapting to changes in mobile network feature capability and service exposure. Furthermore, it is designed to cope with variations in mobile network data speed and latency, considering the differences in available throughput, data speed and latency when switching between different 3GPPTM access bearers (i.e. 2G, 3G, LTE and Mobile IoT).\ If data speed and latency is critical to the IoT Service, the IoT Device Application **SHOULD** constantly monitor mobile network speed and connection quality in order to request the appropriate quality of content from the IoT Service Provider’s infrastructure. In tiered IoT Devices, the embedded IoT Service Enablement Layer **SHOULD** constantly monitor mobile network speed and connection quality in order to request the appropriate quality of content from the Cloud Platform. The IoT Device Application retrieves mobile network speed and connection quality information from the IoT Service Enablement Layer. ## Low Power Mode If the IoT Device Application does not need to exchange any data with the IoT Service Platform for a period greater than 24 hours, and the IoT Service can tolerate some latency, the IoT Device **SHOULD** implement a power-saving mode where the device’s communication module/chipset is effectively powered down between data transmissions. This will reduce the IoT Device’s power consumption and reduce mobile network signaling.\ IoT Device Applications communicating over 3GPPTM Mobile IoT access bearers, such as NB-IoT and LTE-M, **SHOULD NOT** power down their communication module/chipset. The 3GPPTM power saving features **SHOULD** be used instead, thus avoiding power-draining, system selection scanning procedures. ## IoT Service Platform Temporarily Unreachable or Offline If the IoT Service Platform is temporarily offline, the IoT Device Application **SHALL** first diagnose if the communication issues to the server are caused by higher layer communications (TCP/IP, UDP, ATM…). Higher layers mechanisms **SHALL** then try to re-establish the connection with the server. This is done by assessing (and if necessary, attempting to re-establish) connectivity in a step-wise approach, top-down. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. The IoT Device Application **SHALL NOT** frequently initiate an application-driven reboot of the communication module/chipset. The IoT Devices **SHALL** retry connection requests to the IoT Service Platform with an increasing back-off period.\ If the IoT Device detects that the IoT Service Platform is back online, it **SHALL** employ a randomized timer\ to trigger communication requests to the mobile network. ## Coverage Lost (GPS, GLONASS, LAN, WAN) When GPS, GLONASS coverage is lost, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. When LAN or WAN coverage is lost, the monolithic IoT Device **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHALL** retry scanning to acquire mobile network connectivity with an increasing back-off period. In tiered IoT Devices, the embedded Service Enablement Layer **SHALL** comply to this requirement. ## Sensor / Actuator Malfunction When in-built sensors or actuators malfunction, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. ## Sensor Alarms / Actuators Triggered When in-built sensors or actuators are triggered, the monolithic IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** instead send an alert to the IoT Server Application. ## Battery Power Low or Power Failure The IoT Device Application **SHOULD** send a notification to the IoT Service Platform with relevant information when there is an unexpected power outage or battery problem. ## Device Memory Full When the IoT Device memory is full, for example due to the amount of collected data or an unwanted memory leak, the IoT Device Application **SHALL NOT** reboot the communication module/chipset. The IoT Device Application **SHOULD** perform diagnostics, reboot the affected hardware element and send an alert to the IoT Server Application. ## Communication Request Fail The IoT Device Application **SHALL** always handle situations when communication requests fail in a way that does not harm the mobile network. The mobile network may reject communication requests from the IoT Device with a 3GPPTM error cause code (refer to GSMA TS.34). When the IoT Device Application detects that its requests are rejected, it **SHALL** retry connection requests to the mobile network with an increasing back-off period. The IoT Device Application **SHALL NOT** start an application-driven reboot of the communication module/chipset, attempting to ignore or override the mobile network’s decision.\ Additionally, the IoT Device Application **SHALL** always be prepared to handle situations when communication requests fail, when such failure is reported by the embedded Service Enablement Layer. Communication requests from the IoT Device Application **SHALL NOT** be retried indefinitely – all requests must eventually time-out and be abandoned by the IoT Device Application. ## Device-Originated SMS are Barred When the IoT Device Application detects that its subscription for MO-SMS is barred by the mobile network, the IoT Device Application **SHALL** retry connection requests to the mobile network with an increasing back-off period. The IoT Device Application **SHALL NOT** start an application-driven reboot of the communication module/chipset. ## Radio Access Technology Bearers Reselection If the IoT Device supports more than one family of access technology (for example 3GPPTM, WLAN) the IoT Device Application **SHALL** employ a randomized delay before switching to a different family of access technology.\ The IoT Device Application **SHALL** implement a protection mechanism to prevent frequent "ping-pong" between these different technologies. This is done by limiting the frequency of reselection actions, with appropriate hysteresis mechanisms. ## Mass Deployments of Devices For mass deployments of IoT Devices (e.g. >10,000 units within the same mobile network), if the monolithic IoT Device supports more than one family of communications access technology (for example 3GPPTM, WLAN) the IoT Device Application **SHALL** employ a randomized delay before switching to a different family of access technology. ## Loss of Roaming Service The IoT Device Application **SHALL** always be prepared to recover lost end-to-end connectivity while camping on a roaming network. This is implemented with a top-down, staged recovery algorithm diagnosing each protocol layer. In case of failing to re-establish one layer, the algorithm initiates the recovery procedure on the following protocol level below. This may be done, for example, as follows: * Step 1. Re-establishment of higher layer connectivity, e.g. VPN tunnels, SSH sessions, etc., * Step 2. Re-establishment of the PDN connectivity or PDP context, * Step 3. Re-attach (data) to the network, * Step 4. Re-triggering of a plain network selection, * Step 5. Complete reboot of the device. All recovery procedures **SHALL**, to avoid excessive sending of signals to the network, be properly implemented. This may include usage of randomized triggers and incremental, back-off retry mechanisms. Threshold and timer values may depend on the IoT Service’s requirements. ## IPv4/v6 Dual Stack Support The IoT Device Application **SHALL** support IPv4/v6 dual stack (PDN Type = IPv4v6) so that it can properly roam onto mobile networks having support for either IPv4 only or IPv6 only or dual stack only. *** # Suggested Limits Please note that these numbers are suggestions which should be noted in the design of an IoT device. Please also note that the metrics are depended on the use case and might be much lower for certain application. These are **NOT** hard limits enforced by 1NCE. ## Suggested Maximum Connection Requests * 2G/3G/4G: 720 connection requests (Network Attach) / day / device (i.e., on average once every two minutes). * NB-IoT/LTE-M: 24 connection requests (Network Attach) / day / device (i.e., on average once per hour). ## Suggested Maximum of Daily Messages * 2G/3G/4G: no limitations * NB-IoT/LTE-M: 120 application messages / day / device (i.e., on average 5 messages per hour); minimal volume per message. ## Suggested Maximum Volume of Data per Single Device * 2G/3G/4G/NB-IoT/LTE-M: 10 Mbytes / month / device; tariff-specific restrictions may occur (e.g., maximum lifetime volume \< 10 Mbytes, or pooling restrictions may be in place limiting the average monthly data volume to 500KB or 1 MB). --- # SMS Services Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/
![Schematic structure of the 1NCE SMS service.](/img/connectivity-services/connectivity-services-sms-services/001.png)
In the world of IoT devices, the Short Message Service (SMS) has still an important role in basic communication with connected devices. The 1NCE SMS Service provides capabilities to send and receive messages with a 1NCE SIM. For more details about this service, refer to the subchapters in the menu on the left side. From the perspective of a device, the 1NCE SMS Service provides the typical sending and receiving possibilities. However, some additional features and limitations for the specific IoT application need to be taken into consideration. In the following sections of this guide, a basic introduction to the features, limitations, terminology, and detailed applications of the SMS service is provided. --- # SMS Examples Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-examples/ --- # Features & Limitations Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-features-limitations/ # Features In addition to sending and receiving MT-SMS, the 1NCE Service offers additional features to provide optimal integration into IoT device workflows and management infrastructures. Details about the implementation and usage of the individual features are available in the individual guide sections. ## Mobile Terminated SMS For sending MT-SMS messages towards an IoT device with a 1NCE SIM, two options are available: * 1NCE Portal: * Submit MT-SMS messages for a single SIM card. * Testing and debugging purposes. * Short-term data retention policy. * 1NCE API: * Submit multiple MT-SMS via automation. * Integration into customer applications possible. * Volume management. * Delivery Reports for MT-SMS. ## Mobile Originated SMS Any device with a 1NCE SIM can send MO-SMS messages. The provided destination mobile number is irrelevant for the delivery process. All MO-SMS messages can be received via two options: * 1NCE Portal: * Low number of messages. * Testing and debugging purposes. * Short-term data retention policy. * 1NCE SMS Forwarder Service: * High number of messages. * Integration into automated customer applications. ## Monitoring SMS Events When an MT-SMS is sent an Event Record is generated. These records can be viewed in the 1NCE Portal or processed through the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) interface. Monitoring the Event Records can help to verify correct device behavior and identify possible connectivity issues. *** # Limitations The 1NCE SMS Service focuses on optimized IoT communication use cases. As a result, some additional limitations compared to the typically expected MT-SMS communication between mobile phones have to be considered. ## SMS Volume Usage Dependent on the tariff of the 1NCE SIM, a certain volume of MT-SMS messages is included. Details about the available volume and usage can be inquired in the 1NCE Portal or through the [1NCE API](/api/). Each MT-SMS message sent (MT or MO) counts towards the used volume. Delivery retry attempts are not counted towards the volume. Once the volume is used up, no more messages can be sent until the volume is topped up. ## SMS Size Limitations The typical limitations of the MT-SMS size also apply to 1NCE SMS. A message can be at most 160 characters long. Longer messages must be split into multiple messages. It is possible to send concatenated MT-SMS via API requests. ## Device-To-Device SMS (P2P) With 1NCE connectivity, it is not possible to send Peer-to-Peer (P2P) MT-SMS between devices. Therefore, it is not possible to send a message to a device with a 1NCE SIM using a mobile phone, neither with a third party nor another 1NCE SIM. For instance, it is possible to set the destination number on a mobile phone and send a message to this number but the Short Message Service Centre (SMSC) will not forward this MT-SMS to the destination number. The MT-SMS service is only intended to exchange messages with a server application controlled by the customer, Application-to-Peer (A2P).
![Schematic diagram showing that SMS to external sources are not supported.](/img/connectivity-services/connectivity-services-sms-services/sms-services-features-limitations/001.png)
## SMS over NB-IoT 1NCE core does not support IP messaging and hence, the devices must receive the message while being connected to the GSM network. Furthermore, while being connected to NB-IoT the dispatch or reception of MT-SMS is not possible. ## SMS Expiry Date & Retry For the case the subscriber is not reachable via MT-SMS, an expiry date can be set which is used to retry the delivery of the MT-SMS. The following sections will cover this behavior in detail. ### MO-SMS When sending a MO-SMS towards a customer-server application using the SMS Forwarding Service, the default delivery expiry time is 24 hours. The delivery retry scheme works exponentially, i.e. the period between the different delivery attempts increases with each attempt. If delivery fails in the first attempt, due to the server being down or an incorrect Forwarding Service setup, the MO-SMS is buffered. In that case, for instance the 1st retry is done after 5 minutes, the 2nd after 15 minutes, each retry counting from the submit time. In case the message cannot be delivered with the default time of 24h, the MO-SMS will expire and no more retry takes place. ### MT-SMS A MT-SMS sent towards a device with a 1NCE SIM, the default expiry time is 24 hours if the message was submitted through the 1NCE Portal. When using the 1NCE API, the expiry time can be changed by customer. If the device with the 1NCE SIM is not reachable at the point of time when the MT-SMS was submitted, the retry mechanism will deliver the message as soon as the SIM attaches to the network the next time and is ready to receive messages, provided the MT-SMS has not expired. ### SMS Validity Time & Data Retention Due to General Data Protection Regulation (GDPR) and the 1NCE data retention policy, a MT-SMS is stored at most seven days. After this period 1NCE deletes the MT-SMS data from the system and the content is no longer available. Therefore, it is recommended to set up the SMS Forwarding Service and Data Streamer Service for using the 1NCE SMS Service to the full extend. ### Originator Address/Number Some devices and network operators require that an originate address or number is provided, otherwise some devices or MNOs will not accept the SMS messages. This originator address does not need to be configured to a specific SIM parameter in the 1NCE IoT domain. Any random numbering should work in this case as any returned SMS from the device are always send to the 1NCE Portal to SMS Forwarder. Please fill out this data when sending SMS via API or 1NCE Portal. --- # Mobile Originated SMS Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-mo-sms/
![Schematic sequence diagram of a MO-SMS message.](/img/connectivity-services/connectivity-services-sms-services/sms-services-mo-sms/001.png)
SMS messages originating from a device with a 1NCE SIM are referred to as Mobile Originated SMS (MO-SMS). Messages sent from an IoT devices with 1NCE SIM are only forwarded to application targets and not other devices. For accessing and receiving the messages, 1NCE offers multiple solutions for different needs. References to examples for all the listed methods are provided. *** # 1NCE Portal The most basic option to receive and visualize MO-SMS is the 1NCE Portal. In the web user interface, the messages and timestamps for individual SIM can be viewed. This is useful for debugging and testing with a limited amount of SIM cards. The data shown in the portal will be retained for seven days. Afterward, the records of the received SMS will no longer be visible. For more details about the usage of the portal, refer to the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. See the [MO-SMS Portal Examples](/docs/blueprints-examples/examples-sms/examples-mo-sms#1nce-portal--sms-console) for an example of MO-SMS in the 1NCE Portal. *** # Management API Besides monitoring SMS relevant parameters via the 1NCE API, it is also possible to query messages for specific SIM from the API. This application is meant for infrequent queries of a small number of messages, e.g. for testing purposes. Although it would be possible to query SMS messages for all SIM regularly, it is not recommended to create unnecessary HTTP Requests and loads on the API. A better solution for receiving large amounts of SMS messages regularly is the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/). The process of querying messages with the API and HTTP Requests is described in the [1NCE API](/api/) documentation. See the [MO-SMS API Examples](/docs/blueprints-examples/examples-sms/examples-mo-sms#1nce-sms-api) for example usage of the 1NCE API for MO-SMS. *** # SMS Forwarding Service For receiving SMS messages in an automated way, the SMS Forwarding Service is the ideal solution. It allows getting push messages via a customer-specified HTTP REST interface. Details about the Forwarding Service can be found in the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) guide. See the [SMS Forwarder Examples](/docs/blueprints-examples/examples-sms-forwarder/) for examples on how to setup, test and use the SMS Forwarder Service. --- # Mobile Terminated SMS Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-mt-sms/
![Schematic diagram of a MT-SMS message.](/img/connectivity-services/connectivity-services-sms-services/sms-services-mt-sms/001.png)
The term Mobile Terminated SMS (MT-SMS) encompasses SMS messages destined for a specific device. As 1NCE connectivity focuses on IoT applications, sending SMS messages from device to device (P2P) is not possible. Therefore, sending messages from a phone or other device towards a terminal with a 1NCE SIM is not possible. The 1NCE SMS Service offers two methods of sending messages towards an device. Please note that some devices require an originator address/number to be set in order to successfully receive an SMS. In the 1NCE IoT use case, the number does not need to match any specific number of the SIM. *** # 1NCE Portal An easy-to-use and very intuitive tool for sending MT-SMS to individual devices with 1NCE SIM is the 1NCE Portal. This method is ideal for debugging and testing purposes as it offers an easy-to-use user interface for sending and monitoring SMS messages. Details on using the portal interface for sending SMS to devices can be found in the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. For sending and receiving larger amounts of SMS and automating this process over longer periods, the 1NCE API is recommended. See also the [MT-SMS Portal Examples](/docs/blueprints-examples/examples-sms/examples-mt-sms#1nce-portal--sms-console) for an example of MT-SMS in the 1NCE Portal. *** # 1NCE SMS API For larger batches or automated messages, the 1NCE API offers a HTTP REST interface for processing requests. Compared to the 1NCE Portal, the API offers more flexibility for automation and optional configuration of advanced SMS parameters (UDH, DCS and Expiry Date). The Data Coding Scheme (DCS) parameter enables GSM 7-bit default alphabet text messages and 8-bit binary data messages. The User Data Header (UDH) is an optional parameter which specifies how a message should be formatted and processed. It is useful for sending concatenated SMS messages consisting of two or more parts. How concatenated messages can be submitted is shown in the [Concatenated SMS Messages](#concatenated-sms-messages) section. See also the [MT-SMS API Examples](/docs/blueprints-examples/examples-sms/examples-mt-sms#1nce-sms-api) for references to sending SMS via API. ## Data Coding Scheme The Data Coding Scheme (DCS) is a value which transports information about how the recipient device shall handle the the transferred data payload. In principle, the DCS specifies the character set of your payload. Based on the chosen DCS the message length varies. The maximum length of a SMS is 160 character using the default GSM character set. You can use another character set and the maximum number of characters which can be used might shrink. In the following table you can see some DCS values and its short descriptions. For a full reference please see Data Coding Scheme Wiki. | DCS Value | Format | Payload for API | | --- | --- | --- | | 0 | 7-Bit Alphabet Text | Message Payload as String *TestSMS* | | 4 | 8-Bit Binary Data | Binary Payload as Hex Encoded String *54657374534d53* | | 8 | UCS-2 | | ## Concatenated SMS Messages In the User Data Header (UDH), the format and processing of an SMS message is specified. This header information is useful for sending a concatenated message which is longer than the 160 character limit. To split a message into multiple parts, each part needs to be sent via a separate API call with the correct UDH header. An example is shown below: | Part Number | User Data Header | Payload | | :---------- | :--------------- | :-------------- | | 1 of 3 | 050003CC 03 01 | Message Part 01 | | 2 of 3 | 050003CC 03 02 | Message Part 02 | | 3 of 3 | 050003CC 03 03 | Message Part 03 | The UDH needs to be accounted for in the total size of the SMS message. Therefore, only 153 7-bit character parts can be sent in one message when the UDH is used to concatenate messages. The UDH consists of six-byte fields: * The total length of UDH * The Information Element Identifier (IEI) * The header length without the first two fields (IEIL) * CSMS reference ID * Total number of SMS parts * Part number For more information about the UDH and SMS concatenation see GSM 03.38 and GSM 03.40. *** # SMS Forwarder Service While it is not possible to directly send MT-SMS with the SMS Forwarding Service, it is possible to receive Delivery Reports (DLR). These reports are sent via the configured forwarding URL, indicating that the MT-SMS was delivered to the target device with a 1NCE SIM. Further details about this service can be found in the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) section. --- # SMS Monitoring Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-sms-monitoring/ Besides sending and receiving MT-SMS and MO-SMS messages, 1NCE offers additional ways to monitor the flow of messages and retrieve log data. Three options are available to explore and gather data for monitoring purposes: 1NCE Portal, 1NCE Data Streamer Service and 1NCE API. In the following sections, the capabilities and benefits of each available interface is presented. *** # 1NCE Portal The 1NCE Portal offers an easy and ready-to-use user interface for monitoring 1NCE services. Regarding SMS services, the overall volume usage and status of messages for each SIM is presented in the portal. Furthermore, the SMS Console offers the functionality to send and receive messages using the web interface. The Event Records from the Data Streamer are listed as part of the user interface. This provides a quick overview of the current events of the 1NCE SIM. Overall the portal offers a good starting point for manual monitoring of small amounts of SIM or easy debugging. The portal offers no automation integration and logging data is deleted after seven days due to the data retention policy. For more details on how to use the 1NCE Portal, please refer to the [My SIMs & SMS Console](/docs/1nce-portal/portal-sims-sms) guide. *** # Data Streamer The Data Streamer offers a stream of Event and/or Usage Records via a wide selection of cloud connectivity applications. This service is ideal for long-term, automated monitoring of a large amount of connected SIM. Regarding the SMS services, the message usage volume and event records for the SMS Forwarding Service are included in the Data Streamer. Upon sending or receiving a message a Usage Record entry is sent via the streaming service, showing the used volume for sending a message. The Event Records also log errors from the SMS Forwarding Service. If the provided REST endpoint is not reachable or does not meet the required configuration, a HTTP 500 Error Event will be logged in the Data Streamer. In this case, please verify the configuration and availability of the provided HTTP endpoint. More details are covered in the [Data Streamer Service](/docs/platform-services/platform-services-data-streamer/) section. *** # SMS Forwarder A further source for monitoring of the SMS Service, including Delivery Reports, MT-SMS, MO-SMS messages and status information is available through the SMS Forwarding Service. Please refer to the [SMS Forwarder Service](/docs/platform-services/platform-services-sms-forwarder/) section for more details. *** # SMS API The 1NCE API does not only allow to send SMS messages via HTTP Requests, but also offers endpoints to query information about the SIM and SMS service on demand and set up certain additional parameters. This includes SMS Volume usage and limits, status messages, old messages with payload, etc. Please note that this data for the API will be held at most seven days, due to the data retention policy. The API is ideal for requesting specific debugging information on demand. It is not recommended to use the API for large automated queries on a regular basis, please use the Data Streaming Service for this automation. Details about the API can be found in the [API](/api/) section of the documentation. --- # SMS Volume Source: https://help.1nce.com/docs/v2/connectivity-services/connectivity-services-sms-services/sms-services-sms-volume/ Dependent on the tariff of the 1NCE SIM, a certain volume of SMS message volume is included. The current state of the volume for each of the SIM can be either viewed in the 1NCE Portal or queried through the [1NCE API](/api/). The following sections will explain what is counted towards the SMS volume usage and list a few example showcases. *** # SMS Volume Usage Using a 1NCE SIM and the SMS Service, each MT-SMS and MO-SMS message count towards the used volume. Important to note is that both "sending" and "receiving" SMS messages from the view of a 1NCE SIM card are considered as usage. Delivery retry attempts, Delivery Reports, the SMS Forwarding Service, and SMS API requests are not counted towards the volume. MT-SMS that are not successfully delivered to a device will not be billed towards the used SMS volume. For MO-SMS, the usage is counted even if the SMS Forwarding Service is not configured as the the SMS is still delivered to the 1NCE backend and displayed in the 1NCE Portal for ease of use. Once the SMS volume is used up, no more messages can be sent until the volume is topped up. Trying to send a message if the volume is used up will result in a Warning Event in the Data Streamer. *** # Self-Set SMS Volume Limits A customer-specified limit for the MO-/MT-SMS message volume can be set in the 1NCE Portal Configuration tab or through the 1NCE API. This limit applies to the SMS message volume for all SIM in the organization. These limits can be used to restrict the message volume usage per month for the SIMs from the network side. The limits can be set in predetermined steps and will be reset on the first day of each new month. ## Reaching and Resetting the Limit If a SIM runs into this limitation, an error message will be issued when submitting a new SMS message through the API **Traffic limit of X SMS per month exceeded** or 1NCE Portal **Set monthly limit of SMS exceeded**. To reenable a SIM, please either wait until the volume is reset at the beginning of the month or manually increate the limit via the 1NCE Portal Configuration tab or 1NCE API. Sending a MO-SMS while the MO-SMS message limit is exceeded, will result in the SMS being rejected to the 1NCE Network. This rejection will result in an error return code from the device modem. > ❗️ Error Warning Exceeded Limit > > Using the 1NCE API if the self-set limit is reached **Traffic limit of X SMS per month exceeded** is returned as error. In the 1NCE Portal **Set monthly limit of SMS exceeded** is shown when the SMS limit was reached and a new SMS is issued.\ > For **MO-SMS** no notification will be shown in the 1NCE Portal or Data Stream. The SMS will be rejected by the network resulting in an error return code from the device modem. *** # Example SMS Usage Scenarios ## One MT/MO-SMS Sending **one** MT-SMS or MO-SMS will charge **one** SMS towards the included volume. ## MT-SMS with MO-SMS Answer The customer sends one MT-SMS via the 1NCE API towards the device, and the device responds with a MO-SMS back towards the customer. In this case, **one** MT-SMS and **one** MO-SMS are sent, resulting in a volume deduction of **two** SMS messages. --- # Internet Breakout Source: https://help.1nce.com/docs/v2/network-services/network-services-internet-breakout/
![](/img/network-services/network-services-internet-breakout/001.png)
The default connectivity for a 1NCE SIM is achieved through the Internet Breakout Service. All devices with a 1NCE SIM can connect freely to services hosted in the public internet space. The Figure above illustrates the basic operation principle of the 1NCE Internet Breakout. Please note that the IPs listed in the Figure are just example placeholders. For the Internet Breakout IPs please refer to the list below for the full available IP pool. Depended on the configured breakout setting in the 1NCE Portal, the behavior of the Internet Breakout will different. *** # Internet Breakout Modes The Internet Breakout setting in the configuration tab allows you to configure the ideal network flow for your SIMs cards for public-facing internet access and private connectivity through VPN. The 1NCE Internet Breakout can be configured in two different variances, which offer different functionality. * Automatic Mode * Manual Mode The breakout setting allows you to select the nearest local Internet Breakout to minimize latency in data transfer. Your SIM card can either **Automatically** select the geographically nearest breakout, or you can **Manually** set the location of the breakout. > 📘 Default Setting > > With the release (20.09.2022) of the configurable Internet Breakout setting, existing customers breakout will remain as Europe (Frankfurt) as before the feature introduction. > > New Organizations and newly created Suborganizations will use the Automatic Mode by default. This setting can be changed in the 1NCE Portal configuration tab. ## Automatic Mode When using the Automatic Mode, **each individual SIM** data traffic towards the public internet is routed through the geographically optimized data center based on the SIM location to allow for low latency internet access. The automatic system selected the ideal breakout region for each individual SIM independently. This results in SIMs exiting through different breakouts dependent on their location. 1NCE is using AWS to facilitate dynamic Internet Breakout in the Automatic Mode. The closest breakout region is dynamically chosen based on the device location. Different availability zones inside the breakout region serve as backup to prevent downtime. > 📘 VPN and 1NCE OS > > OpenVPN and 1NCE OS Services are currently not available in the **Automatic Mode** due to the automatically changing breakout IPs. While Automatic Mode is active, the OpenVPN Configuration tab is disabled. ### Example Configurations One customer SIM device is located and connected in Germany. Based on the given location, the automatic Internet Breakout determines that the Europe (Frankfurt) is the ideal location to breakout the public internet traffic. The customer can expect their public internet traffic to exit from one of the breakout IPs from Europe (Frankfurt). A second SIM device is located and connected in New York USA. As the SIM devices is closest to the US East breakout, the automatic system determines that US East (N. Virginia) should be used to exit the public internet traffic of the SIM. The traffic from this specific SIM will exit through the US East (N. Virginia) Internet Breakout IPs. ## Manual Mode When selecting a specific breakout region using the Manual Mode, **all SIMs** public internet access will be routed through the selected breakout region. All SIMs of the customer (sub) organization are locked to the selected manual breakout region, independent on the actual device location. > 📘 VPN and 1NCE OS > > The 1NCE VPN Service is available in the **Manual Mode**. The specific regional adaptions of the [OpenVPN Configuration](/docs/1nce-portal/portal-configuration#openvpn-configuration) need to be applied. > > 1NCE OS is currently only available through the Europe (Frankfurt) and US East (N Virginia) breakout regions. Currently, five regions are available: * Europe (Frankfurt) * US West (N. California) * US East (N. Virginia) * Asia-Pacific (Tokyo) * South America (São Paulo) ### Example Configurations The Manual Mode is set to Europe (Frankfurt) for the example organization. One customer SIM device is located and connected in Germany. Independent of the given location, the manual Internet Breakout Europe (Frankfurt) is used to breakout the public internet traffic. The customer can expect their public internet traffic to exit from one of the breakout IPs from Europe (Frankfurt). A second SIM device is located and connected in New York USA. The SIM devices is closest to the US East breakout, but due to the Manual Mode, the traffic will be routed through the Europe (Frankfurt) exit to the public internet. The traffic from this specific SIM will exit through the Europe (Frankfurt) Internet Breakout IPs. ## Optimized Breakout Countries Using the automatic breakout mode, the traffic of SIM devices will switch breakout based on the operator to which the device is connected. With the automatic mode, this switching is automatically optimized to deliver the lowest latency possible through an internet breakout. When using a manual breakout the list of optimized countries should also be considered. Selecting a manual breakout for a non-optimized country or operator could lead to worse latency overall. Therefore it only makes sense to change the manual breakout if the SIM devices are located within the optimized countries. ### United States Please note that our US breakouts are currently optimized for SIM cards deployed and roaming within the USA. For this reason it is impossible to take advantage of their benefits if a SIM is located outside the country. We are already working on a timely global extension. ### Asia-Pacific Breakout For the following countries, the Asia-Pacific breakout will be used in automatic mode. When using the manual breakout configuration, switching to Asia-Pacific is beneficial if most SIM devices are located within these regions: Australia, Cambodia*, China, Hong Kong, Indonesia, Japan, South Korea, Malaysia*, Mongolia, New Caledonia, New Zealand, Philippines, Sri Lanka, Taiwan*, Thailand*. *not for all operators in the country {/* ### South America (São Paulo) */} *** # Internet Breakout IPs Each available Breakout Region has its unique set of IP Addresses. The specific IP address selected for the Internet Breakout of a SIM card is randomly chosen and can not be managed by the customer. Depending on your configuration, all IPs or Region-specific ones should be used for whitelisting the 1NCE Internet Breakout service. Note that the used IPs are depended on the selected Breakout Mode: * **Automatic mode**: all IP addresses * **Manual Mode**: IPs matching the configured Region ## List of IP Addresses The currently used IPs to breakout any internet-targeted traffic are listed below. Please note that these IP addresses might change overtime as new resources and features upgrades are introduced. ### Europe (Frankfurt) | | | |---|---| | `3.127.42.194 ` | `3.74.85.174` | ### US East (N. Virginia) | | | |---|---| | `52.22.204.173` | `35.168.126.164` | ### Asia-Pacific (Tokyo) | | | |---|---| | `13.159.208.126` | `57.181.13.73` | ## Data Streamer and additional Service IPs The currently used IPs for the additional services are listed in the table below. Please note that these IP addresses might change overtime as new resources and features upgrades are introduced. ### Europe (Frankfurt) | | | |---|---| | `35.158.28.90 ` | `35.158.7.81 ` | | `3.67.238.112 ` | ` ` | *** # Network Address Translation By design, the internet access for 1NCE SIMs is implemented with Network Address Translation (NAT). The NAT maps the private SIM-IP to commonly used public 1NCE breakout IP. This network design simplifies IP space management and enhances the access security of connected IoT devices. As a result, devices with a 1NCE SIM cannot be directly accessed from the public internet side, thus improving the resilience against external attacks and threads targeting the IoT devices. Using the 1NCE Internet Breakout, the **connection establishment** is **unidirectional** (e.g., SIM towards server/service), while **data transfer** over an already **established connection** is **bidirectional** (e.g., SIM towards server/service and server/service towards SIM). The flow of the 1NCE Internet Breakout is shown in the sequence diagram below. Bidirectional connection establishment can only be achieved using the 1NCE VPN Service.
![Sequence diagram of the 1NCE Internet Breakout.](/img/network-services/network-services-internet-breakout/002.png)
*** # Data Protocols The concept of the Open Systems Interconnection model applies to the 1NCE Data Service structure. The GPRS Tunneling Protocol (GTP) is used on layer 3 to transfer user application data between the device with a 1NCE SIM and the internet or application server and vice versa. All the data traffic is wrapped in the GTP, on top of this protocol (layer 4+) the customer is free to use any transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port assignment. *** # Domain Name System (DNS) The Domain Name System (DNS) is used to resolve Uniform Resource Locators (URL) to an addressable IP. When using the 1NCE Internet Breakout, the public IP `8.8.8.8` is served as primary and `8.8.4.4` as secondary default Domain Name Server. A manual configuration of a DNS on the device is typically not needed but can be configured, if desired. *** # Maximum Transmission Unit (MTU) Size The Maximum Transmission Unit (MTU) is the size of the largest IP packet (layer 4) possible which can be transferred in a respective frame on layer 3 without the need for fragmentation in the packet based core network. If a send packet is larger than the specified MTU, the packet needs to be fragmented, thus creating more overhead and delays. Theoretically, a size of 1500 bytes is possible with the 1NCE Data Service. Based on prior experience with IoT devices and mobile networks, it is recommended to keep the **MTU size lower than about 1200 bytes**. *** # Internet Breakout Timeout The Internet Breakout does not have a static NAT timeout for pending connections. Please consider that timeouts for inactive TCP and UDP connections. For established TCP connections the timeout is 600 seconds and for UDP the timeout is 120 seconds. After the respective timeout and no further data transmission, the TCP /UDP connections will be closed. New TCP and UDP connections can be opened at any point of time, there is no need to reattach the SIM device with a new PDP. *** # Breakout IP Blacklisting The traffic from all 1NCE SIMs towards the public internet is routed through a NAT with a the listed public-facing IP addresses. These public breakout IPs are listed above under Internet Breakout IPs. The specific IP address selected for the Internet Breakout is randomly chosen and can not be managed by the customer. > ❗️ Whitelist 1NCE Breakout IPs > > Ensure that the 1NCE Internet Breakout IPs are whitelisted for custom service infrastructure accessed by 1NCE SIMs through the Internet Breakout. Large quantities of SIMs accessing the same service can lead automated firewall and protection mechanisms to block the 1NCE Breakout IPs. All requests towards public internet services appear to come from these IPs. Most public services and APIs (e.g. time services, open source APIs, etc.) apply a request limit and smart filtering to detect and filter out denial of service (DDoS) and similar attacks. Very frequent queries (e.g., every second) from multiple SIMs towards one endpoint could trigger these filtering mechanisms. This will result in the public service blocking requests from 1NCE SIM devices, rendering the service unusable. Most public services cannot differentiate between individual SIMs due to the 1NCE NAT network structure. It is strongly recommended to program devices with 1NCE SIMs in a way that they do not aggressively query such shared resources. Using customer-controlled resources (e.g. custom server, AWS or similar cloud service), the protection control mechanisms can be configured to whitelist the traffic originating from the 1NCE NAT Breakout. --- # VPN Service Source: https://help.1nce.com/docs/v2/network-services/network-services-vpn-service/
![](/img/network-services/network-services-vpn-service/001.png)
Each 1NCE SIM has a private IP and is connected via the Internet Breakout using Network Address Translation to the public internet. By default the connection establishment is unidirectional from the SIM device to a server/service in the internet. The 1NCE VPN Service enables 1NCE customers to connect and transmit data bidirectional with their SIM devices via a Virtual Private Network (VPN) connection. A VPN describes a technology that encapsulates and transmits Internet Protocol (IP) network data, over a separate network. Virtual Private Networks are commonly used to enable access to parts of a network that are otherwise inaccessible from the open internet. 1NCE uses the open-source implementation OpenVPN as the basis for the VPN Service. The Figure provides a high-level overview of the VPN Service. The VPN provides mutual communication between devices with a SIM and their application server endpoints with the VPN client. The 1NCE VPN Service is available in Manual Mode for the selected Breakout Setting and the usage of this service is optional and free of charge. Even if the VPN Service is used, the default NAT Internet Breakout is still available for requests towards the internet using. 1NCE provides three different OpenVPN Server Endpoints matching each available Breakout region that can be configured. --- # Features & Limitations Source: https://help.1nce.com/docs/v2/network-services/network-services-vpn-service/vpn-service-features-limitations/
![](/img/network-services/network-services-vpn-service/vpn-service-features-limitations/001.png)
This chapter provides a high-level, abstract overview of the features and limitations of the 1NCE VPN Service. It shows the extended possibilities and benefits of the VPN, compared to the regular Internet Breakout capabilities of the 1NCE SIM. In addition, the limitations of the service are pointed out. *** # Features The 1NCE VPN Service is available in Manual Mode for the selected Breakout Setting and the usage of this service is optional and free of charge. In the following section, the main features and function of this service will be shown. ## Bidirectional Communication Establishment Compared to the default Internet Breakout capabilities of the 1NCE SIM Connectivity, the VPN Service allows bidirectional communication establishment (see Figure above). An IoT device with a 1NCE SIM can communicate directly to an application server by addressing the VPN client endpoint IP of this server. Vise versa, the application server can reach a listening 1NCE SIM device with an active PDP context (data session) via the VPN tunnel interface by setting up the communication to the static IP addresses of the SIM. This setup is required for the server-to-device initiated communication using common Internet Protocols or remote SSH connections to access the mobile device. The customer is free to use any user transport protocol (e.g., TCP, UDP, MQTT, CoAP, etc.) and any port number over the VPN connection. ## Internet Breakout As the 1NCE VPN Service is available in parallel with the normal Internet Breakout connectivity, a device with a 1NCE SIM can still use the normal internet connectivity while the VPN connection is established. This has the benefit that sensitive data can be sent via the VPN endpoint IP address to a server, but general requests (e.g., NTP or public API queries) can be directly done by the device without the need to set up forwarding internet traffic through the VPN connection. The 1NCE VPN Service is not available if the Automatic Mode for the Internet Breakout is used. For using the 1NCE VPN Service, please set a manual Internet Breakout Region. The VPN configuration is specific for each individual Breakout Region. Please download the matching VPN config from the 1NCE Portal. After a change in the breakout settings, the VPN client needs to be altered with the region-specific configuration. One VPN client at a time can be used and each VPN client IP will be different per breakout region. The client IP for each region is static with the given credentials but might change e.g. due to a customer requested token update. 1NCE always suggests to use DNS to dynamically resolve the private VPN client IP on the SIM devices. Hardcoding the IP address of any component such as VPN client or SIM device is not recommended. ## Enhanced Security The 1NCE VPN Service offers overall improved connection security. All SIM-related traffic exchanged between the 1NCE Core network and the customer application server can be sent over the VPN connection by using the assigned SIM or IP ranges respectively. This private virtual network offers direct access to the SIM with no other public traffic to worry about and filter. All tunnel traffic is handled over one port and connection, which is easier to integrate and maintain. ## No Additional Cost The 1NCE VPN Service is included for all 1NCE SIM customers and is not extra charged. The usage of the VPN does not produce more overhead with regards to the data volume usage. Transmitting data via the default Internet Breakout or the 1NCE VPN Service will result in the same usage of data volume for the SIM. All the traffic sent and received by a SIM is accounted as volume usage independent of the VPN usage. ## Globally distributed Servers The 1NCE VPN Service is available in all three Breakout Regions for selection in the Manual Mode. Each Breakout provides a dedicated OpenVPN Server to provide the flexibility to select the closest location to your application server. *** # Limitations Due to technical constraints, certain limitations apply to the 1NCE VPN Service, which needs to be taken into consideration. ## OpenVPN Version 3 Currently version 3 of the OpenVPN client is not natively supported by the 1NCE VPN Service. It is recommended to use the latest OpenVPN version 2.x for connecting to the VPN and using the direct SIM data connection. ## OpenVPN Version 2.6.x Updates For customers upgrading their existing OpenVPN version to 2.6 and above might need to download a new 1NCE configuration file from the 1NCE Portal. Some parameters were optimized for the newer versions of OpenVPN, the basic configuration and IP addresses will remain the same as before. ## VPN Connection Limit The 1NCE VPN Service supports one active VPN client connection per (sub-) organization (see Figure below) at a time. If multiple clients try to connect at the same time, inconsistent data connections with random disconnects between the clients will occur. For establishing multiple connections to the 1NCE network, please refer to the IPSec Service or create additional suborganizations. Every (sub-) organization receives its own access data.
![Overview showing that multiple VPN connections are not possible.](/img/network-services/network-services-vpn-service/vpn-service-features-limitations/002.png)
## VPN Client IP Routes When the OpenVPN client establishes as connection to the VPN server all required network routes will be pushed to the client, ensuring that all SIM cards of an organization can be reached from the client. There will be one network route entry per assigned IP address space. Though the OpenVPN server does not push changes in routes while a VPN connection is established. Consequently, the OpenVPN must be restarted to receive routes for additional IP address spaces. If you have received additional SIM cards you may want to check the 1NCE Portal if any new IP address spaces were added to your organization. > ❗️ New IP Spaces > > Please restart your VPN connection if you ordered a large new batch of SIMs which received a different IP Space range. ## Conflicting IP Ranges As 1NCE uses private IP spaces (RFC 1597) for the connectivity SIM and OpenVPN client, there is a chance for an IP address conflict if the same IP address range is used in your local network or data center. To resolve this issue, the local network IP addresses can be changed or the 1NCE VPN Service access needs to be segregated from the rest of the affected network. ## VPN Client Password Length Some OpenVPN client implementations are limited to a password length of smaller than 128 characters. As the credentials provided by the 1NCE VPN Service are longer than this limitation, in rare cases this will cause an AUTH\_FAILED response when connecting to the VPN server. This issue can be mitigated by upgrading to a more recent OpenVPN implementation or changing the password length parameter during compiling. In the case an update is possible, we recommend to implement the VPN Client Service on a different server system. If an update or other deployment is not possible and the issue is consistent, please contact the 1NCE support for further advice. ## Default Traffic Routing When using the 1NCE VPN Service, only data routed by the single connected device towards the OpenVPN Client IP is actually sent to the customer-side VPN endpoint. All other traffic is transmitted using the default Internet Breakout. For an application case where all traffic (DNS , NTP, etc.) should be accessible through the VPN , the routes on the connected device with the 1NCE SIM needs to be adapted by the customer. ## Maximum Transmission Unit Size Using the 1NCE VPN, some device connections might have issues with the Maximum Transmission Unit (MTU) size. A symptom is often that larger payloads do not get delivered. To avoid this issue, please lower the MTU to 1300 using the `tun-mtu 1300` configuration parameter in the VPN client configuration. ## Internet Breakout Region VPN is not available if the Automatic Mode for the Internet Breakout is used. To use the VPN Service, please set a manual Internet Breakout Region. The VPN configuration is specific for each individual Breakout Region. Therefore, after a change in the breakout setting the VPN client needs to be altered with the region-specific configuration. The VPN client IP will be different for each of the possible Internet Breakout Regions. This needs to be taken into consideration when designing the SIM device firmware. ## Inactive VPN Connection Deactivation VPN connections not actively in use should be disconnected by the customer. After three months of VPN inactivity, 1NCE reserves the right to deactivate the VPN connection from the core network side. This measure helps to maintain network efficiency and security. If a VPN connection has been deactivated due to inactivity, the existing VPN configuration will no longer be operational. To resume VPN service usage, a new credential file must be downloaded from the 1NCE Customer Portal and the connection must be reconfigured. --- # OpenVPN Files Source: https://help.1nce.com/docs/v2/network-services/network-services-vpn-service/vpn-service-openvpn-files/ > 📘 OpenVPN Files Download > > Both the configuration and credential file can be downloaded from the configuration page of the 1NCE Portal. This section provides a general description of the tunnel interface of the VPN Service as well as an overview of the configuration and credential files. For setup and testing guides for different operating systems, please refer to the VPN Setup Guide. *** Tunnel Interface Connecting the VPN client on PC or server creates a separate tunnel network interface. All mobile originated and mobile terminated data traffic is sent through this tunnel interface and will be routed according to the destination IP address. When using the 1NCE VPN Service, the device with the 1NCE SIM can reach the customer VPN endpoint by addressing the static IP of the client application. In the other way, the application server can reach each individual device by addressing the static IP of the SIM. For opening or pinging a server to SIM device connection it is important that the SIM is attached to the network and the device modem has an active PDP data session open. *** # OpenVPN Configuration Files VPN Client File When downloading the VPN configuration file (see extract below), two different file formats for Windows and Linux are available. The content of both files is almost identical. The only difference is the `auth-user-pass` entry in the file. This line points the VPN client towards the `credentials.txt` file for authenticating the user on the VPN server. The default path is different for the two operating systems but can be changed to the specific of the operating system or VPN client. The `remote` address and port of the VPN server should not be changed. It has to be ensured that both the domain address and the given port are configured in any firewall or access system to allow a connection towards the 1NCE VPN server. The table below shows the default config provided by 1NCE. Some parameters can be **adapted** (✔) while others should be **not changed** (❌). 1NCE does not recommend changing or altering the default configuration and does not guarantee that changes in the configuration will provide the expected connectivity. | Config Parameter | Default Value | Customizable | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----------------------------: | :----------: | | **client** Indicates that the `xx-region-x-client.ovpn` file is a client configuration. | | ❌ | | **dev** Virtual network device set to Tunnel (TUN), simulates a network layer device and operates with layer 3 IPv4 and IPv6 packets. Tunnel interface name can be changed to `tun` where `` is a integer number. | `tun` | ✔ | | **proto** Protocol setting for communicating with remote host. | `udp` | ❌ | | **remote** Remote host name or IP address. | ` ` | ❌ | | **resolv-retry** If hostname resolve fails for –remote, retry resolve for n seconds before failing. | `infinite` | ✔ | | **nobind** Do not bind to local address and port. The IP stack will allocate a dynamic port for returning packets. | | ❌ | | **explicit-exit-notify** Send server an exit notification if tunnel is restarted or OpenVPN process is exited. Number of attempts that the client will try to resend the exit notification. | `3` | ❌ | | **keepalive** Simplification of –ping and –ping-restart. Checks the current connection state by ICMP PING. Settings are ``. | `5 30` | ✔ | | **(user)** Change the user ID of the OpenVPN process after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. This is option only included in the `xx-region-x-client.conf` file for Linux operating systems. | `root` | ✔ | | **(group)** Optional group to be owner of this tunnel. This is option only included in the `xx-region-x-client.conf` file for Linux operating systems. | `nogroup` | ✔ | | **persist-key** Don't re-read key files across SIGUSR1 or --ping-restart. | | ❌ | | **persist-tun** Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts. | | ❌ | | **remote-cert-tls** Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules. | `server` | ❌ | | **verb** Set output verbosity. Level 3 is recommended if you want a good summary of what’s happening without being swamped by output. | `3` | ✔ | | **auth-nocache** VPN client will not cache the username and password needed for authentication in virtual memory. This will prevent the log entry "WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this" upon connection establishment. | | ✔ | | **auth-user-pass** Authenticate with server using username/password from a file containing username/password on 2 lines. | ` /etc/openvpn/credentials.txt` | ✔ | | **auth-retry** Controls how OpenVPN responds to username/password verification errors such as the client-side response to an AUTH_FAILED message from the server or verification failure of the private key password. | `nointeract` | ✔ | | **tun-mtu** Optional parameter Maximum Transmission Units. In most cases, leave this parameter set to its default value. In case of issues with HTTPS or SSH connections, try lowering this value. | `1500` | ✔ | | **certificates** Certificates included in the config file. | | ❌ | More information about the configuration options can be found in the OpenVPN Reference Manual. Password Cache Warning If detailed logging is setup for the OpenVPN client, the following warning might appear when the OpenVPN client is started: _WARNING: this configuration may cache passwords in memory -- use the auth-nocache option to prevent this._ This warning can be avoided by adding the `auth-nocache` parameter into the OpenVPN client configuration file. This should usually have no side affects, nevertheless the [official documentation](https://community.openvpn.net) states: “If specified, this directive will cause OpenVPN to immediately forget username/password inputs after they are used. As a result, when OpenVPN needs a username/password, it will prompt for input from `stdin`, which may be multiple times during the duration of an OpenVPN session.“ VPN Credential File The `credentials.txt` file downloaded from the CMP (see extract below) contains a user id as username and an access token as password for the 1NCE VPN server. The content of this file does not need to be modified. The location of this file needs to be set in the VPN Config File `xx-region-x-client.ovpn`. ```text credentials.txt ``` --- # VPN Setup Source: https://help.1nce.com/docs/v2/network-services/network-services-vpn-service/vpn-service-setup-guides/ --- # Data Streamer Service Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/
![Schematic diagram of the Data Streamer Service structure.](/img/platform-services/platform-services-data-streamer/001.png)
Access to the SIM status, events, and usage data is a key factor when it comes to monitoring and debugging IoT-focused systems. This type of data could be queried from the 1NCE API, but this generates a lot of undesired overhead traffic and load. The ideal solution for getting 1NCE SIM-related event and usage data as a stream is the 1NCE Data Streamer Service. The Data Streamer Service allows subscribing to real-time Event and Usage Records for all SIM cards. Incoming information is pushed directly to a customer-specified server endpoint with the Rest API integration or an already integrated cloud service such as AWS S3, Kinesis, DataDog, Keen.io, etc. For more details about this service, refer to the subchapters in the menu on the left side. In this chapter of the Developer Hub Guide, the Features of the Data Streamer, as well as the Setup possibilities and an overview of the Event and Usage Records are shown. --- # Event Records Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-event-records/ The 1NCE Data Streamer Service offers a stream of Event and Usage Records. This chapter will focus on the Event Record specification. The exact format of the events is dependent on the used integration. In this chapter, the focus lies on the JSON Object format. Please note that empty, nested JSON objects are listed as NULL objects. For other integrations the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used. The following sections will cover the individual parts of the Event Record JSON: * [Generic Properties](#generic-properties) * [Additional Properties](#additional-properties) * [Detail Properties](#detail-properties) * [PDP Context Object](#pdp-context-object) *** ## Example Event Records Let us start with a few Example Event Records in the form of JSON Objects from the Data Streamer. Listed below in the different tabs are some example Event Records for different Event Types. All Examples are in the JSON Format just like it would be delivered by the Data Streamer with the custom HTTP endpoint method. Please note that some fields only include placeholder or example values. Furthermore, some of the fields might be dependent on the used Radio Access Technology and other variables.
01_Update_Location ```json 01_Update_Location.json { "imsi": { "imsi": "", "id": 123456, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from VLR for IMSI='', now attached to VLR=''.", "alert": false, "id": 1234567890, "user": null, "detail": { "mnc": [ { "mnc": "20", "id": 327 }, { "mnc": "16", "id": 328 } ], "tapcode": [ { "tapcode": "NLDDT", "id": 470 }, { "tapcode": "NLDPN", "id": 471 } ], "name": "T-Mobile", "country": { "iso_code": "nl", "country_code": "31", "name": "Netherlands", "id": 141, "mcc": "204" }, "id": 730 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 1, "description": "Update location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
02_Update_GPRS_Location ```json 02_Update_GPRS_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "New location received from SGSN for IMSI='', now attached to SGSN='', IP='', RAT type='E_UTRAN'.", "alert": false, "id": 1234567, "user": null, "detail": { "mnc": [ { "mnc": "01", "id": 2 } ], "tapcode": [ { "tapcode": "DEUD1", "id": 1 }, { "tapcode": "DEUK9", "id": 851 } ], "name": "T-Mobile", "country": { "iso_code": "de", "country_code": "49", "name": "Germany", "id": 74, "mcc": "262" }, "id": 2 }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456789 }, "event_type": { "id": 2, "description": "Update GPRS location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
03_Create_PDP_Context ```json 03_Create_PDP_Context { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "New PDP Context successfully activated with SGSN CP=, DP=.", "alert": false, "id": 1234567890, "user": null, "detail": { "pdp_context": { "tx_teid_control_plane": 3162410000, "sgsn_control_plane_ip_address": "", "sac": null, "ratezone_id": "2171", "rat_type": 2, "tunnel_created": "2021-08-09T12:00:27", "breakout_ip": "unavailable", "tariff_id": "442", "mnc": "01", "apn": "iot.1nce.net", "ue_ip_address": "", "gtp_version": 1, "rac": null, "region": "eu-central-1", "tx_teid_data_plane": 2014413000, "ggsn_data_plane_ip_address": "", "ci": 5559, "tariff_profile_id": "129000", "pdp_context_id": 110753000, "imsi": "901405100000000", "operator_id": "2", "mcc": "262", "imeisv": "863576047850000", "sgsn_data_plane_ip_address": "", "ggsn_control_plane_ip_address": "", "lac": 38701, "nsapi": 5, "rx_teid": 110750000 }, "name": "T-Mobile", "id": 2, "country": { "mcc": "262", "iso_code": "de", "name": "Germany", "id": 74, "country_code": "49" } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 3, "description": "Create PDP Context" }, "timestamp": "2019-01-21T09:36:17Z" } ```
05_Delete_PDP_Context ```json 05_Delete_PDP_Context.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "PDP Context deleted.", "alert": false, "id": 12345678000, "user": null, "detail": { "pdp_context": { "tx_teid_control_plane": 3162419000, "sgsn_control_plane_ip_address": "", "sac": null, "rat_type": 2, "tunnel_created": "2021-08-09T12:00:27", "breakout_ip": null, "mnc": "01", "apn": null, "ue_ip_address": "", "gtp_version": 1, "rac": null, "region": "eu-central-1", "tx_teid_data_plane": 2014410000, "ggsn_data_plane_ip_address": "", "ci": 5500, "pdp_context_id": 110753000, "imsi": "901405100000000", "mcc": "262", "imeisv": "8635760478506578", "sgsn_data_plane_ip_address": "", "ggsn_control_plane_ip_address": "", "lac": 38700, "nsapi": 5, "rx_teid": 110753000 }, "name": "T-Mobile", "id": 2, "volume": { "rx": 0, "tx": 0, "total": 0 }, "country": { "mcc": "262", "iso_code": "de", "name": "Germany", "id": 74, "country_code": "49" } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 5, "description": "Delete PDP Context" }, "timestamp": "2019-01-21T09:36:17Z" } ```
09_SIM_Suspension ```json 09_SIM_Suspension.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "Status of SIM changed from 'Activated' to 'Suspended'", "alert": false, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456 }, "event_type": { "id": 9, "description": "SIM suspension" }, "timestamp": "2019-01-21T09:36:17Z" } ```
08_SIM_Activation ```json 08_SIM_Activation.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2019-01-21T09:36:17Z" }, "description": "Status of SIM changed from 'Suspended' to 'Activated'", "alert": false, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": null, "id": 123456 }, "event_type": { "id": 8, "description": "SIM activation" }, "timestamp": "2019-01-21T09:36:17Z" } ```
16_Purge_GPRS_Location ```json 16_Purge_GPRS_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SGSN location information has been purged for IMSI=''.", "alert": false, "id": 12345678, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 16, "description": "Purge GPRS location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
15_Purge_Location ```json 15_Purge_Location.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "INFO" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "VLR location information has been purged for IMSI=''.", "alert": false, "id": 12345678, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 123456 }, "event_type": { "id": 15, "description": "Purge location" }, "timestamp": "2019-01-21T09:36:17Z" } ```
18_Data_Quota_Threshold_Reached ```json 18_Threshold_Reached.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 12345678, "production_date": "2019-01-21T09:36:17Z" }, "description": "Endpoint quota threshold reached, volume is below 20%.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "threshold_volume": 118.983794, "volume": 118.968383, "threshold_percentage": 20 } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 18, "description": "Quota threshold reached" }, "timestamp": "2019-01-21T09:36:17Z" } ```
19_Data_Quota_Used_Up ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Quota volume is completely used up and data access denied for endpoint.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "threshold_volume": 100, "volume": "0.015085", "threshold_percentage": 20 } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 19, "description": "Quota used up" }, "timestamp": "2019-01-21T09:36:17Z" } ```
20_SMS_Threshold_Reached ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota threshold reached, volume is below 20%.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "volume": 0, "threshold_percentage": 20, "threshold_volume": 1, "traffic_type": { "id": 6, "description": "SMS" } } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 20, "description": "SMS quota threshold reached" }, "timestamp": "2019-01-21T09:36:17Z" } ```
21_SMS_Quota_Used_Up ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota volume is completely used up and SMS access denied for endpoint.", "alert": true, "id": 1234567890, "user": null, "detail": { "quota": { "volume": 1, "threshold_percentage": 20, "threshold_volume": 1, "traffic_type": { "id": 6, "description": "SMS" } } }, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 21, "description": "SMS quota used up" }, "timestamp": "2019-01-21T09:36:17Z" } ```
52_Data_Quota_Enabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "Data quota management got enabled for service profile (id = 123123 - Generic with Quota or Limits), endpoints of this service profile without an active data quota will be throttled or blocked from data service.", "id": 1234567890, "event_type": { "id": 52, "description": "Data quota enabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
53_Data_Quota_Disabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "Data quota management got disabled for the service profile (id = 123123 - Generic with Quota or Limits).", "id": 1234567890, "event_type": { "id": 53, "description": "Data quota disabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
54_SMS_Quota_Enabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "SMS quota management got enabled for service profile (id = 123123 - Generic with Quota or Limits), endpoints of this service profile without an active SMS quota will be blocked from SMS service.", "id": 1234567890, "event_type": { "id": 54, "description": "SMS quota enabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
55_SMS_Quota_Disabled ```json 19_Quota_Used_Up.json { "timestamp": "2019-01-21T09:36:17Z", "alert": false, "description": "SMS quota management got disabled for the service profile (id = 123123 - Generic with Quota or Limits).", "id": 1234567890, "event_type": { "id": 55, "description": "SMS quota disabled" }, "event_source": { "id": 2, "description": "API" }, "event_severity": { "id": 1, "description": "Warn" }, "organisation": { "id": 1234, "name": "87123123" } } ```
56_Data_Quota_Assigned ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Data quota got assigned with volume of 500.000000 MB. On exhaustion, the data service will be blocked.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 56, "description": "Data quota assigned" }, "detail": "{\"endpoint_quota_id\":123123, \"quota_status_id\": 1,\"action_on_quota_exhaustion_id\": 1,\"volume\": 500.000000, \"expiry_date\": 2022-03-31T00:00:00Z, \"peak_throughput\": 128000,\"last_volume_added\": 500.000000,\"last_status_change_date\": 2022-03-24T12:46:27Z, \"auto_refill\": true,\"threshold_percentage\": 20,\"threshold_volume\": 100.000000}", "timestamp": "2019-01-21T09:36:17Z" } ```
57_Data_Quota_Deleted ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "Data quota got deleted and data service will be blocked for this endpoint until new data quota got assigned.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 57, "description": "Data quota deleted" }, "timestamp": "2019-01-21T09:36:17Z" } ```
58_SMS_Quota_Assigned ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota got assigned with volume of 250 SMS. On exhaustion, the SMS service will be blocked.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 58, "description": "SMS quota assigned" }, "detail": "{\"endpoint_quota_id\":123123, \"quota_status_id\": 1,\"action_on_quota_exhaustion_id\": 1,\"volume\": 500.000000, \"expiry_date\": 2022-03-31T00:00:00Z, \"peak_throughput\": 128000,\"last_volume_added\": 500.000000,\"last_status_change_date\": 2022-03-24T12:46:27Z, \"auto_refill\": true,\"threshold_percentage\": 20,\"threshold_volume\": 100.000000}", "timestamp": "2019-01-21T09:36:17Z" } ```
59_SMS_Quota_Deleted ```json 19_Quota_Used_Up.json { "imsi": { "imsi": "", "id": 1234567, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "API", "id": 2 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 0, "description": "Info" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS quota got deleted and SMS service will be blocked for this endpoint until new SMS quota got assigned.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 59, "description": "SMS quota deleted" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_SMS_Forwarder ```json 00_SMS_Forwarder.json { "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": null, "imsi": null, "detail": null, "description": "Unable to dispatch DLR to API Callback URL '' (HTTP code=400), please verify the URL is correct and the application server is accepting requests.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_Disabled_Endpoint ```json 00_Disabled_Endpoint.json { "imsi": { "imsi": "", "id": 12345678, "import_date": "2019-01-21T09:36:17Z" }, "event_source": { "description": "Policy Control", "id": 1 }, "organisation": { "name": "8100xxxx", "id": 1234 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2019-01-21T09:36:17Z" }, "description": "Disconnecting data access for endpoint, because it has been disabled.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 1234567 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
00_SMS_API ```json 00_SMS_API.json { "event_source": { "description": "Network", "id": 0 }, "organisation": { "name": "8100xxxx", "id": 12345 }, "event_severity": { "id": 1, "description": "WARN" }, "sim": { "msisdn": "", "iccid": "", "id": 1234567, "production_date": "2019-01-21T09:36:17Z" }, "description": "SMS to cannot be forwarded, because no API Callback URL defined in service profile.", "alert": true, "id": 1234567890, "user": null, "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678 }, "event_type": { "id": 0, "description": "Generic" }, "timestamp": "2019-01-21T09:36:17Z" } ```
*** ## Generic Properties Generic Properties are fields that are always included in an Event Record JSON message received via the Data Streamer. The following table will list all these properties, their data type, and a short description. | Property | Data Type | Description | | :--------------- | :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | LONG (64 bit) | Unique ID for each Event Record sent. Duplicate received event IDs indicate possible retransmissions. | | `timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the event occurrence in the ISO 8601 format. | | `event_type` | JSON Object | Object with an id and a description about the occurred event. See [Event Types](#event-types) for a list of all possible values. | | `event_severity` | JSON Object | JSON object with an id and a description about the severity of the event. See [Event Severity](#event-severity) for a list of all possible values. | | `event_source` | JSON Object | An id and a description about the source of the event. See [Event Source](#event-source) for a list of all possible values. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Event Organization](#event-organization) for more information. | | `alert` | BOOLEAN | Events with a high impact on connectivity operation are flagged as an Alert. | | `description` | STRING | String with a human readable description of the event. | ### Event Types The different types of events are indicated by the Event Type nested object. This object contains an ID and a short description of the event. The following table lists all possible Event Types that can be received via the Data Streamer. | Event ID | Description | | :------- | :-------------------------------- | | 0 | Generic | | 1 | Update location | | 2 | Update GPRS location | | 3 | Create PDP Context | | 4 | Update PDP Context | | 5 | Delete PDP Context | | 6 | User authentication failed | | 7 | Application authentication failed | | 8 | SIM activation | | 9 | SIM suspension | | 10 | SIM deletion | | 11 | Endpoint blocked | | 12 | Organization blocked | | 13 | Support Access | | 14 | Multi-factor Authentication | | 15 | Purge Location | | 16 | Purge GPRS location | | 17 | Self-Signup | | 18 | Data Quota Threshold reached | | 19 | Data Quota used up | | 20 | SMS Quota Threshold reached | | 21 | SMS Quota used up | | 30 | OpenVPN authentication | | 50 | SIM Released | | 51 | SIM Assigned | | 52 | Data Quota Enabled | | 53 | Data Quota Disabled | | 54 | SMS Quota Enabled | | 55 | SMS Quota Disabled | | 56 | Data Quota Assigned | | 57 | Data Quota Deleted | | 58 | SMS Quota Assigned | | 59 | SMS Quota Deleted | | 60 | Data Quota expired | ### Event Severity The severity levels of an event indicate what impact the event has on the correct operation of the system. The possible Event Severity values are listed below: | Severity ID | Description | | :---------- | :---------- | | 0 | INFO | | 1 | WARNING | | 2 | CRITICAL | ### Event Source Based on the Event Type, a different originating Event Source might be responsible for triggering the event. The possible sources consisting of an ID and a Description are listed below. | ID | Description | | :- | :------------- | | 0 | Network | | 1 | Policy Control | | 2 | API | ### Event Organization Each Event Record includes information about the originating organization. This helps to identify the organization in the use case of multiple Data Streamer for sub organizations. The JSON property fields of this object are listed below. | Property | Data Type | Description | | :------- | :-------- | :----------------------------- | | `id` | INTEGER | Unique ID of the organization. | | `name` | STRING | 1NCE Customer ID. | *** ## Additional Properties Event Records that directly relate to SIMs, Endpoints, or Users might include some of the following optional properties. | Property | Data Type | Description | | :--------- | :---------- | :------------------------------------------------------------------------------------------------ | | `imsi` | JSON Object | International Mobile Subscriber Identity, see [IMSI Object](#imsi-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM Object](#sim-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint Object](#endpoint-object) for more information. | ### IMSI Object The International Mobile Subscriber Identity is used to identify each device with a SIM. The following parameters are included in an Event Record. | Property | Data Type | Description | | :------------ | :-------------- | :-------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the IMSI. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | | `import_date` | TIMESTAMP (UTC) | Timestamp when the IMSI was provisioned in the ISO 8601 format. | ### SIM Object Each SIM card has unique properties and parameters. This data is included in the event stream. A list of the available data fields is shown below. | Property | Data Type | Description | | :---------------- | :-------------- | :---------------------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | | `production_date` | TIMESTAMP (UTC) | Timestamp when the SIM was produced in the ISO 8601 format. | ### Endpoint Object As a SIM is placed inside a device, some information about this endpoint is transferred via the mobile network. This information is useful to identify the specific device type and certain connection parameters. A list of all Endpoint Objects is listed below. | Property | Data Type | Description | | :----------- | :-------- | :--------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the Endpoint. | | `name` | STRING | Name of the Endpoint configuration. | | `ip_address` | STRING | Specific static IP Address of the SIM card/Endpoint. | | `tags` | STRING | Any Tags assigned to the Endpoint. | | `imei` | STRING | International mobile equipment identity of the Endpoint/Device with the SIM. | *** ## Detail Properties For certain Event Types, additional information parameters are added in the Detail Properties. A list of the object parameters and fields is listed below. | Property | Data Type | Description | | :------------ | :---------- | :------------------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID for the used mobile network operator. | | `name` | STRING | Name of the mobile network operator. | | `country` | JSON Object | Country of the mobile network operator. See [Country Object](#country-object) for more information. | | `pdp_context` | JSON Object | Object with details about the PDP Context. See [PDP Context Object](#pdp-context-object) for more information. | | `volume` | JSON Object | Object with details about the Volume used. See [Volume Object](#volume-object) for more information. | ### Country Object A nested JSON object inside the Detail Properties contains more information about the country where the SIM event took place. The fields of the Country JSON are listed below. | Property | Data Type | Description | | :---------------------- | :-------- | :------------------------ | | `country.id ` | INTEGER | Unique ID of a country. | | `country.name ` | STRING | Name of the country. | | `country.country_code ` | STRING | Country Code | | `country.mcc` | STRING | Mobile Country Code (MCC) | | `country.iso_code ` | STRING | ISO Country Code | ### PDP Context Object An Event Record for a PDP Context includes a wide range of additional information in the Detail Properties. The individual fields are listed below. | Property | Data Type | Description | | --- | --- | --- | | `pdp_context_id` | INTEGER | ID of the PDP Context. | | `tunnel_created` | TIMESTAMP (UTC) | Creation time of the PDP Session. | | `gtp_version` | STRING | GTP Version 1/2 | | `ggsn_control_plane_ip_address ` | STRING | IP Address of GGSN/PGW Control Plane | | `ggsn_data_plane_ip_address` | STRING | IP Address of GGSN/PGW Data Plane | | `sgsn_control_plane_ip_address` | STRING | IP Address of SGSN/SGW Control Plane | | `sgsn_data_plane_ip_address` | STRING | IP Address of SGSN/SGW Data Plane | | `region` | STRING | Region of the Data Plane. | | `breakout_ip` | STRING | IP Address used for the Internet Breakout. | | `apn` | STRING | Access Point Name (APN) | | `nsapi` | INTEGER | Network Service Access Point Identifier (NSAPI) | | `ue_ip_address ` | STRING | IP address of the device. | | `imeisv` | STRING | International Mobile Equipment Identity - Softwareversion | | `mcc` | STRING | Mobile Country Code (MCC) | | `mnc` | STRING | Mobile Network Code (MNC) | | `lac` | INTEGER | Location Area Code (LAC) | | `sac` | INTEGER | Service Area code (SAC) | | `rac` | INTEGER | Routing Area code (RAC) | | `ci` | INTEGER | Cell Identification (CI) | | `rat_type` | INTEGER | Radio Access Type (RAT) 1 - 3G 2 - 2G 5 - HSPA+ 6 - LTE\* 8 - NB-IoT 9 - CAT-M\* | \* Only from some mobile operators *rat\_type* 9 is sent for CAT-M connections (depends on the 3GPP Release in their Core Network). For the majority of the CAT-M connections the rat\_type in the data streamer is 6, since CAT-M is based on the 4G standard. ### Volume Object With each PDP Context, some information about the Data Usage is included in the Volume JSON. The content description of the fields is listed below. | Property | Data Type | Description | | :------------- | :------------ | :------------------------------ | | `volume.rx` | DECIMAL(14,6) | Downstream Volume in MegaBytes. | | `volume.tx` | DECIMAL(14,6) | Upstream Volume in MegaBytes. | | `volume.total` | DECIMAL(14,6) | Total Volume Usage. | --- # Features & Limitations Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-features-limitations/ # Features ## Event and Usage Monitoring With the 1NCE Data Streamer Service, customers can get live-streamed Event and Usage Records for their 1NCE SIM cards. This allows 1NCE customers to monitor the current connectivity status of each SIM individually in near real-time. The Usage Records provide additional insight into the data and SMS volume usage patterns of the connected IoT devices. The data streamer helps 1NCE customers to keep an eye on the IoT connectivity of their devices with a 1NCE SIM card. ## Multi-Target Streaming The 1NCE Data Streamer Service allows configuring multiple target applications for the same streamed data. This allows the customer to integrate both the Event and Usage Records into multiple data analytics and monitoring systems at once. Each configured receiver will get the latest updates pushed. The individual streams can be configured in the 1NCE Portal under the Configuration Tab. In the Portal, individual data streams can also be paused/resumed, and deleted. ## Data Analytics Platforms The usage and event stream can be integrated into the most commonly used platforms for data analytics and monitoring. 1NCE provides ready to use integrations for some selected 3rd party platforms. Currently the 1NCE Data Streamer supports the following integrations options: * Keen.io * DataDog * AWS S3 * AWS Kinesis ## Custom API Endpoint In addition to the ready to use 3rd party integrations, 1NCE offers the possibility to integrate an own HTTP Post Endpoint which can be configured to receive the records from the data streamer. Customers can use this integration to include the 1NCE Data Streamer Service into their application or monitoring system of choice. *** # Limitations ## DataDog Integration The DataDog integration only provides Data Volume monitoring capabilities. That means only Data Volume in Bytes is reported, and SMS consumption cannot be monitored. --- # Network Events Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-network-events/ # Network Events The 1NCE Data Streamer Service provides a real-time stream of Network Events from your IoT devices and network infrastructure. These Network Events give you comprehensive visibility into device connectivity, location updates, data usage, quota management, and system activities. The exact format of the Network Events depends on the integration used, but this chapter focuses on the JSON Object format delivered by the Data Streamer. Network Events are categorized into several types: * [Network Events](#network-events-1) - Location updates and network attachments * [PDP Context Events](#pdp-context-events) - Data session lifecycle * [SIM Management Events](#sim-management-events) - SIM activation and status changes * [Quota Events](#quota-events) - Data and SMS quota management * [System Events](#system-events) - VPN and endpoint management *** ## Network Event Structure Overview All Network Events share a common structure with the following main components: * [Generic Properties](#generic-properties) - Always present in every Network Event * [Additional Properties](#additional-properties) - Optional SIM, IMSI, and endpoint information * [Detail Properties](#detail-properties) - Network Event-specific additional information *** ## Example Network Events Here are sample Network Events from different categories showing the JSON structure delivered by the Data Streamer:
Network Event ```json { "id": 12345678, "timestamp": "2024-12-13T12:49:57.000Z", "event_type": { "id": 1, "description": "Update location" }, "event_severity": { "id": 0, "description": "INFO" }, "event_source": { "id": 0, "description": "Network" }, "organisation": { "id": 100018, "name": "81013181" }, "alert": false, "description": "New location received from VLR for IMSI = '901405105682328', now attached to VLR = '491720215095'", "sim": { "id": 10000106, "iccid": "8988228066605682328", "msisdn": "882285105682328" }, "imsi": { "id": 100000106, "imsi": "901405105682328" }, "endpoint": { "id": 100000325, "imei": "8697060538230193", "name": "8988228066605682328", "ip_address": "10.0.0.180" }, "detail": { "id": 3, "name": "Vodafone", "country": { "id": 74, "mcc": "262", "name": "Germany", "iso_code": "de", "country_code": "49" }, "mnc": [ { "id": 3, "mnc": "02" } ], "tapcode": [ { "id": 2, "tapcode": "DEUD2" } ] } } ```
PDP Context Event ```json { "id": 12345679, "timestamp": "2024-12-13T12:48:24.000Z", "event_type": { "id": 3, "description": "Create PDP Context" }, "event_severity": { "id": 0, "description": "INFO" }, "event_source": { "id": 0, "description": "Network" }, "organisation": { "id": 100710, "name": "81016541" }, "alert": false, "description": "New PDP Context successfully activated with SGSN CP=139.7.133.222, DP=139.7.133.231.", "sim": { "id": 10000675, "iccid": "8988228530100000018", "msisdn": "882285301000018" }, "imsi": { "id": 100000676, "imsi": "901405301000018" }, "endpoint": { "id": 100000821, "imei": "3500196576514927", "name": "8988228530100000018", "ip_address": "10.0.0.24" }, "detail": { "id": 3, "name": "Vodafone", "country": { "id": 74, "mcc": "262", "name": "Germany", "iso_code": "de", "country_code": "49" }, "pdp_context": { "pdp_context_id": 2382739057, "tunnel_created": "2024-12-13T12:48:24", "ue_ip_address": "10.0.0.24", "apn": "stg.eu.ng.1nce.net", "rat_type": 6, "mcc": "262", "mnc": "02" } } } ```
Quota Event ```json { "id": 17254295, "timestamp": "2025-10-06T03:22:07.622Z", "event_type": { "id": 19, "description": "Quota used up" }, "event_severity": { "id": 1, "description": "WARN" }, "event_source": { "id": 1, "description": "Policy Control" }, "organisation": { "id": 75488, "name": "90000004" }, "alert": true, "description": "Quota volume is completely used up and data access denied for endpoint.", "sim": { "id": 10005527, "iccid": "8988228066680001098", "msisdn": "882285106459880" }, "imsi": { "id": 100005527, "imsi": "901405180001098" }, "endpoint": { "id": 100000489, "imei": "8686990578761101", "name": "8988228066680001098", "ip_address": "10.0.0.21" }, "detail": { "quota": { "id": 876, "volume": -0.6077737808227539, "total_volume": 500, "threshold": { "volume": 100, "percentage": 20 }, "expiry_date": "2035-12-19T00:00:00Z" } } } ```
SIM Management Event ```json { "id": 17369194, "timestamp": "2025-10-09T10:52:27Z", "event_type": { "id": 8, "description": "SIM activation" }, "event_severity": { "id": 0, "description": "INFO" }, "event_source": { "id": 2, "description": "API" }, "organisation": { "id": 99971, "name": "81053872" }, "alert": false, "description": "Status of SIM changed from 'Suspended' to 'Activated'", "endpoint": { "id": 100112571, "imei": "", "ip_address": "10.0.0.2", "name": "2234567890000030861" }, "imsi": { "id": 100050655, "imsi": "223456000032900" }, "sim": { "iccid": "2234567890000030861", "id": 10050478, "msisdn": "223456000032190" } } ```
*** ## Generic Properties Generic Properties are fields that are always included in a Network Event JSON message received via the Data Streamer. These properties provide essential information about every Network Event. | Property | Data Type | Description | | :--------------- | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | LONG (64 bit) | Unique ID for each Network Event sent. Duplicate received Network Event IDs indicate possible retransmissions. | | `timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the Network Event occurrence in the ISO 8601 format. | | `event_type` | JSON Object | Object with an id and a description about the occurred Network Event. See [Event Types](#event-types) for a list of all possible values. | | `event_severity` | JSON Object | JSON object with an id and a description about the severity of the Network Event. See [Event Severity](#event-severity) for a list of all possible values. | | `event_source` | JSON Object | An id and a description about the source of the Network Event. See [Event Source](#event-source) for a list of all possible values. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Event Organization](#event-organization) for more information. | | `alert` | BOOLEAN | Network Events with a high impact on connectivity operation are flagged as an Alert. | | `description` | STRING | String with a human readable description of the Network Event. | ### Event Types The different types of Network Events are indicated by the Event Type nested object. This object contains an ID and a short description of the Network Event. The following table lists all possible Event Types that can be received via the Data Streamer. | Event ID | Description | | :------- | :----------------------------------------- | | 1 | Update location | | 2 | Update GPRS location | | 3 | Create PDP Context | | 4 | Update PDP Context | | 5 | Delete PDP Context | | 8 | SIM activation | | 9 | SIM suspension | | 11 | Endpoint blocked | | 15 | Purge location | | 16 | Purge GPRS location | | 18 | Quota Threshold Reached | | 19 | Quota used up | | 20 | SMS Quota Threshold Reached | | 21 | SMS quota used up | | 29 | OpenVPN disconnect | | 30 | OpenVPN authentication | | 42 | Endpoint enabled | | 43 | Endpoint disabled | | 52 | Data quota enabled | | 53 | Data quota disabled | | 54 | SMS quota enabled | | 55 | SMS quota disabled | | 56 | Data quota assigned | | 57 | Data quota deleted | | 58 | SMS quota assigned | | 59 | SMS quota deleted | | 60 | Data quota expired | | 61 | SMS quota expired | | 100 | Regional Pool Data Quota used up | | 101 | Regional Pool Data Quota Threshold Reached | | 102 | Regional Pool SMS Quota used up | | 103 | Regional Pool SMS Quota Threshold Reached | | 121 | Endpoint deleted | ### Event Severity The severity levels of a Network Event indicate what impact the Network Event has on the correct operation of the system. The possible Event Severity values are listed below: | Severity ID | Description | | :---------- | :---------- | | 0 | INFO | | 1 | WARN | | 2 | WARN | | 3 | ERROR | | 4 | CRITICAL | ### Event Source Based on the Event Type, a different originating Event Source might be responsible for triggering the Network Event. The possible sources consisting of an ID and a Description are listed below. | ID | Description | | :- | :------------- | | 0 | Network | | 1 | Policy Control | | 2 | API | ### Event Organization Each Network Event includes information about the originating organization. This helps to identify the organization in the use case of multiple Data Streamer for sub organizations. The JSON property fields of this object are listed below. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------ | | `id` | INTEGER | Unique identifier of the organization | | `name` | STRING | Name of the organization | *** ## Additional Properties Network Events that directly relate to SIMs, Endpoints, or Users might include some of the following optional properties. | Property | Data Type | Description | | :--------- | :---------- | :------------------------------------------------------------------------------------------------ | | `imsi` | JSON Object | International Mobile Subscriber Identity, see [IMSI Object](#imsi-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM Object](#sim-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint Object](#endpoint-object) for more information. | | `user` | STRING | User identifier if the Network Event was triggered by a specific user action. | ### IMSI Object The International Mobile Subscriber Identity is used to identify each device with a SIM. The following parameters are included in a Network Event. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------------------------ | | `id` | INTEGER | Unique ID of the IMSI. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | ### SIM Object Each SIM card has unique properties and parameters. This data is included in the Network Event stream. A list of the available data fields is shown below. | Property | Data Type | Description | | :------- | :-------- | :--------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | ### Endpoint Object As a SIM is placed inside a device, some information about this endpoint is transferred via the mobile network. This information is useful to identify the specific device type and certain connection parameters. A list of all Endpoint Objects is listed below. | Property | Data Type | Description | | :----------- | :-------- | :--------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID of the Endpoint. | | `name` | STRING | Name of the Endpoint configuration. | | `ip_address` | STRING | Specific static IP Address of the SIM card/Endpoint. | | `tags` | STRING | Any Tags assigned to the Endpoint. | | `imei` | STRING | International mobile equipment identity of the Endpoint/Device with the SIM. | *** ## Detail Properties For certain Network Event Types, additional information parameters are added in the Detail Properties. The content varies based on the Network Event Type and provides specific context for that Network Event category. ### Network Detail Properties Network Events include operator and country information in their detail properties. | Property | Data Type | Description | | :-------- | :---------- | :-------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID for the used mobile network operator. | | `name` | STRING | Name of the mobile network operator. | | `country` | JSON Object | Country of the mobile network operator. See [Country Object](#country-object) for more information. | | `mnc` | ARRAY | Array of Mobile Network Code objects with id and mnc fields. | | `tapcode` | ARRAY | Array of TAP code objects with id and tapcode fields. | ### PDP Context Detail Properties PDP Context Events include comprehensive information about the data session in their detail properties. | Property | Data Type | Description | | :------------ | :---------- | :------------------------------------------------------------------------------------------------------------- | | `id` | INTEGER | Unique ID for the used mobile network operator. | | `name` | STRING | Name of the mobile network operator. | | `country` | JSON Object | Country of the mobile network operator. See [Country Object](#country-object) for more information. | | `pdp_context` | JSON Object | Object with details about the PDP Context. See [PDP Context Object](#pdp-context-object) for more information. | ### Quota Detail Properties Quota Events include quota information and optionally regional pool details. | Property | Data Type | Description | | :-------------- | :---------- | :------------------------------------------------------------------------------------------- | | `quota` | JSON Object | Object with details about the quota. See [Quota Object](#quota-object) for more information. | | `regional_pool` | JSON Object | Object with regional pool information (for regional pool Network Events). | ### VPN Detail Properties VPN Events include client and connection information. | Property | Data Type | Description | | :------- | :---------- | :------------------------------------------------------ | | `vpn_id` | INTEGER | OSS VPN ID | | `region` | STRING | AWS region code | | `client` | JSON Object | Object with version, private\_ip, and public\_ip fields | ### Country Object A nested JSON object inside the Detail Properties contains more information about the country where the SIM Network Event took place. The fields of the Country JSON are listed below. | Property | Data Type | Description | | :------------- | :-------- | :------------------------ | | `id` | INTEGER | Unique ID of a country. | | `name` | STRING | Name of the country. | | `country_code` | STRING | Country Code | | `mcc` | STRING | Mobile Country Code (MCC) | | `iso_code` | STRING | ISO Country Code | ### PDP Context Object A Network Event for a PDP Context includes a wide range of additional information in the Detail Properties. The individual fields are listed below. | Property | Data Type | Description | | :------------------------------ | :-------------- | :--------------------------------------------------------------------------------------------------------- | | `pdp_context_id` | INTEGER | ID of the PDP Context | | `tunnel_created` | TIMESTAMP (UTC) | Creation time of the PDP Session | | `gtp_version` | INTEGER | GTP Version 1/2 | | `ggsn_control_plane_ip_address` | STRING | IP Address of GGSN/PGW Control Plane | | `ggsn_data_plane_ip_address` | STRING | IP Address of GGSN/PGW Data Plane | | `sgsn_control_plane_ip_address` | STRING | IP Address of SGSN/SGW Control Plane | | `sgsn_data_plane_ip_address` | STRING | IP Address of SGSN/SGW Data Plane | | `region` | STRING | Region of the Data Plane | | `breakout_ip` | STRING | IP Address used for the Internet Breakout | | `apn` | STRING | Access Point Name (APN) | | `nsapi` | INTEGER | Network Service Access Point Identifier (NSAPI) | | `ue_ip_address` | STRING | IP address of the device | | `imeisv` | STRING | International Mobile Equipment Identity - Software version | | `mcc` | STRING | Mobile Country Code (MCC) | | `mnc` | STRING | Mobile Network Code (MNC) | | `lac` | INTEGER | Location Area Code (LAC) | | `sac` | INTEGER | Service Area code (SAC) | | `rac` | INTEGER | Routing Area code (RAC) | | `ci` | INTEGER | Cell Identification (CI) | | `rat_type` | INTEGER | Radio Access Type (RAT): 1 = 3G, 2 = 2G, 5 = HSPA+, 6 = LTE, 8 = NB-IoT, 9 = CAT-M | | `gtp_v1_uli` | JSON Object | GTP V1 User Location Information with lac, ci, sac, rac fields | | `gtp_v2_uli` | JSON Object | GTP V2 User Location Information with cgi, sai, rai, tac, eci, lac, menbi, emenbi fields | | `tx_teid_data_plane` | INTEGER | PGW/GGSN TEID user\_plane | | `tx_teid_control_plane` | INTEGER | PGW/GGSN TEID control\_plane | | `rx_teid` | INTEGER | Received Tunnel Endpoint Identifier | | `tariff_id` | STRING | Tariff identifier | | `operator_id` | STRING | Operator identifier | | `ratezone_id` | STRING | Rate zone identifier | | `ipcan_session_id` | STRING | IP-CAN session identifier | ### Quota Object Quota Events include detailed information about quota status and usage. The content description of the fields is listed below. | Property | Data Type | Description | | :------------------------- | :-------------- | :-------------------------------------------------------------- | | `id` | INTEGER | Unique quota identifier | | `volume` | DECIMAL | Remaining volume (can be negative if exceeded) | | `total_volume` | DECIMAL | Total allocated volume | | `accumulated_total_volume` | DECIMAL | Sum of all quota allocations | | `last_volume_added` | DECIMAL | Most recent quota addition | | `service` | STRING | Service type: "data" or "sms" | | `threshold` | JSON Object | Object with volume and percentage fields for threshold settings | | `threshold_percentage` | INTEGER | Percentage threshold (0-100) | | `threshold_volume` | DECIMAL | Calculated threshold volume | | `expiry_date` | TIMESTAMP (UTC) | When the quota expires | | `created_at` | TIMESTAMP (UTC) | When the quota was created | | `status` | JSON Object | Object with id and description for quota status | *** ## Network Event Categories Network Events are organized into the following functional categories: ### Network Events Network Events track device location changes and network attachments. **Update Location (ID: 1)** * Sent when endpoint changes CS (Circuit Switched) network location * Includes VLR attachment information **Update GPRS Location (ID: 2)** * Sent when endpoint changes PS (Packet Switched) network location * Includes SGSN attachment information **Purge Location (ID: 15)** * Sent when CS network location information is cleaned up **Purge GPRS Location (ID: 16)** * Sent when PS network location information is cleaned up ### PDP Context Events PDP Context Events track the lifecycle of data sessions. **Create PDP Context (ID: 3)** * Sent when endpoint establishes a data session * Includes comprehensive PDP context details * Also sent for IMEI lock violations **Update PDP Context (ID: 4)** * Sent when data session is updated * Includes updated PDP context information **Delete PDP Context (ID: 5)** * Sent when data session is terminated * Includes final PDP context state ### SIM Management Events SIM Management Events track SIM lifecycle and status changes. **SIM Activation (ID: 8)** * Sent when SIM status changes to activated **SIM Suspension (ID: 9)** * Sent when SIM status changes to suspended/disabled **Endpoint Enabled (ID: 42)** * Sent when endpoint status is set to enabled **Endpoint Disabled (ID: 43)** * Sent when endpoint status is set to disabled **Endpoint Blocked (ID: 11)** * Sent when endpoint is blocked (e.g., monthly limit exceeded) **Endpoint Deleted (ID: 121)** * Sent when endpoint is deleted from organization ### Quota Events Quota Events track data and SMS quota management and usage. **Data Quota Events** * Data quota enabled/disabled (ID: 52/53) * Data quota assigned/deleted (ID: 56/57) * Data quota expired (ID: 60) * Quota threshold reached (ID: 18) * Quota used up (ID: 19) **SMS Quota Events** * SMS quota enabled/disabled (ID: 54/55) * SMS quota assigned/deleted (ID: 58/59) * SMS quota expired (ID: 61) * SMS quota threshold reached (ID: 20) * SMS quota used up (ID: 21) **Regional Pool Events** * Regional pool data/SMS quota used up (ID: 100/102) * Regional pool data/SMS quota threshold reached (ID: 101/103) ### System Events System Events track infrastructure and service activities. **VPN Events** * OpenVPN authentication (ID: 30) * OpenVPN disconnect (ID: 29) These Network Events include VPN client details and connection information. *** ## Network Event Processing When processing Network Events from the Data Streamer: 1. **Check Network Event ID**: Use the unique `id` field to detect retransmissions 2. **Monitor Alerts**: Pay attention to Network Events where `alert` is `true` 3. **Filter by Severity**: Use `event_severity` to focus on critical issues 4. **Track Organizations**: Use `organisation` to separate multi-tenant scenarios 5. **Parse Detail Properties**: Extract Network Event-specific information from the `detail` object based on Network Event type --- # Setup Guides Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-setup-guides/ In this chapter, the setup of the 1NCE Data Streamer Service for different cloud integrations will be shown in detail. The 1NCE Data Streamer Service offers the following integrations:
![](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/d47972b-rest_api.svg)
Click on one of the icons to get to the setup guide for the selected integration. *** # General Setup Information ## Stream Types When configuring the 1NCE Data Streamer Service, different Stream Types are selectable. The options can be configured for each Data Streamer setup. It can be selected between either Usage Data or Event Data. A combined stream of Usage and Event Data is not supported and can therefore not be selected in the management portal. ## Warnings & Errors In the case that there was an error with Data Streamer connection, a warning record with respective error code is shown in the Data Streamer configuration. In this case, please verify that the service is reachable and is set up correctly. The streamer service uses a back off systems design that retries sending data to the desired destination in case of an failure. Please note that after a certain retry count the streamer goes into FAILED state. If the streamer is in the error state, please try to restart or recreate the stream integration in the 1NCE Portal. ## Stream Management With the 1NCE Data Streamer, it is possible to set up multiple streams with different destinations at once. Each new connection can be configured independently of the others in the 1NCE Portal. A connection can be paused/started or deleted independently of the other setups. To change the configuration of a stream, the old stream has to be deleted and a new stream needs to be set up. Please note that the pausing/starting and creation of a stream can take a few seconds to become active. *** # REST API - Integration The REST API connection to the Data Streamer is ideal for custom server application integrations. This method offers the most flexible, custom integration of the Data Streamer Service into existing analytics, reporting, and monitoring pipelines. The REST API supports both Event and Usage Records.\ The customer server needs to provide an HTTP POST endpoint (see [Endpoint URL](#endpoint-url)). The 1NCE Data Streamer posts a list of events as they occur towards this endpoint.\ As of Version 2.0 of the Data Streamer, events are always provided in BULK mode. Therefore, a list of JSON Event or Usage Record is delivered to the given Endpoint. Using Bulk mode, each HTTP POST will include an array of objects. The maximum amount of records per sent request is 3000 JSON objects in a list. The POST requests are sent at intervals. The endpoint consumes the HTTP POST by sending the HTTP 200 Code as a response to the incoming request. The Data Streamer does not respond to HTTP redirect codes (3xx).\ The HTTP integration uses a retry mechanism with a backoff policy. After a given time, the Data Streamer will go into FAILED state and stop delivering events. After the potential error in the HTTP endpoint behavior has been resolved by the customer, the Data Streamer needs to be restarted by the customer. In the Connectivity Management Platform (CMP), a Basic Authentication Header needs to be set when configuring the REST API integration. This header is of the Base64 format consisting of the `username:password`. The server application endpoint can implement the Basic Authentication Method and only accept incoming requests with the correct header. This offers enhanced security and protection against any requests that do not originate from the 1NCE Data Streamer Service.\ For **testing purposes only**, the Basic Authentication Header value can be set to an arbitrary string and the processing on the server-side can be ignored. We strongly recommend doing this only for **TESTING**. In a production environment, we suggest **ALWAYS** implementing the Basic Authentication Method. ## Endpoint URL The endpoint URL for the Data Streamer in the CMP needs to be valid. URL with public IP addresses (`https://://`) are not supported. Custom ports for the endpoint can be configured via the URL (`https://://`). ## Certificates The endpoint server needs to have a valid SSL/TLS certificate. A self-signed certificate will not work in this application case. We recommend using [Let's Encrypt](https://letsencrypt.org/de/) certificates. ## Endpoint Capacity Be aware that the REST API integration will deliver the incoming events as a list of JSON objects. Dependent on the amount of SIMs and occurred records this request can be quite large. A maximum limit of 3000 records per request is set. 1NCE customers with a large quantity of SIMs and high number of events as such must be aware that their backend system receiving data from the stream needs to have the capacity to handle large incoming requests. *** # Keen.io - Integration The Keen.io platform is a managed event streaming platform used for streaming, analyzing, and embedding rich data. The 1NCE Data Streamer Service can easily be integrated with this service. The Keen.io integration supports both Event and Usage Records. The following items are required for the setup process with Keen.io: * Keen.io Account * New Keen.io Project * Project ID Key * Write Key of the Project * Collection Name In the 1NCE Connectivity Management Platform (CMP), select the desired Stream Type and Keen.io as API Type. Enter the Product ID key and the Write Key of the created Keen.io project. Further the Collection Name is needed to indicate where to stream the data to.\ After the Data Stream integration was created, the first data will be arriving at Keen.io. The incoming data can be seen on the streams tab. *** # DataDog - Integration DataDog is a cloud monitoring service that can be used to monitor the endpoint volume of the 1NCE SIM cards using custom dashboards and trigger events. Please ensure that the region of the used DataDog account matches with the Data Streamer setup fields. To create a DataDog integration, the following is required: * DataDog Account * API Integration * API Key * DataDog Account Region For the configuration of the DataDog Data Streamer integration enter the API Key and the account Region in the Connectivity Management Platform configuration. After the stream was created, data will be transferred to DataDog. In the DataDog explorer, the incoming data can be monitored. The following metrics can be viewed in DataDog: endpoint.volume, endpoint.volume\_tx, endpoint.volume\_rx, and endpoint.cost. When selecting the Stream Type, please note that Event Records are currently not available in DataDog. *** # AWS - Integrations The 1NCE Data Streamer Service can be integrated with both AWS S3 and AWS Kinesis. AWS Kinesis is ideal for collecting and processing large streamed data records in real-time. AWS S3 is an object-based storage solution. The Data Streamer can push CSV files into a S3 bucket allowing for easy, largescale data collection and further processing later on by related AWS Services.\ Both AWS S3 and Kinesis are integrated using AWS IAM Trust Relationships. The setup of the AWS integration can be done through the Connectivity Management Portal (CMP). ## S3 - Integration The S3 integration will provide the Event or Usage Records through an S3 bucket where they are uploaded as CSV files. The CSV filenames for events are `events_YYYYMMDD_HHmmss.csv` and `cdr_YYYYMMDD_HHmmss.csv` for usage records. Each file contains a collection records over a small period. A sample for an event record file type is provided below. ```text cdr_20210512_070123.csv "id","event_start_timestamp","event_stop_timestamp","organisation_id","organisation_name","endpoint_id","sim_id","iccid","imsi","operator_id","operator_name","country_id","operator_country_name","traffic_type_id","traffic_type_description","volume","volume_tx","volume_rx","cost","currency_id","currency_code","currency_symbol","ratezone_tariff_id","ratezone_tariff_name","ratezone_id","ratezone_name","endpoint_name","endpoint_ip_address","endpoint_tags","endpoint_imei","msisdn_msisdn","sim_production_date","operator_mncs","country_mcc" "4427264xxx","2021-05-11 11:17:25","2021-05-11 11:19:51","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.000741","0.000395","0.000346","0.0007410000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" "4427320xxx","2021-05-11 11:17:29","2021-05-11 11:24:56","19xxx","8100xxxx","9673xxx","1500xxx","89882806660010xxxxx","9014051010xxxxx","4","EPlus","74","Germany","5","Data","0.003210","0.001803","0.001407","0.0032100000","1","EUR","€","442","1NCE Production 01 - 1Mbps","21xx","Rate Zone 1 (DE)","89882806660010xxxxx","x.x.x.x",,"35933907591xxxxx","8822851010xxxxx","2019-01-21 08:45:01","0x","2xx" ``` ## Cloud Formation Setup The easiest setup for the stream integration into AWS S3 is by using the Cloud Formation Template via the 1NCE Connectivity Management Portal (CMP). As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. **1.** Open the CMP and navigate to *Configuration>Data Streams>Add New Data Stream*.\ **2.** In the popup select AWS S3 as *API Type* and select the desired *Stream Type*.\ **3.** Click on *Create IAM Role* (see Figure below) to open the Cloud Formation Template in a separate window. ![cmp_popup_ds.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/2c56973-cmp_popup_ds.png) **4.** Adapt the CFN Template parameters (Stack Name, S3BucketName). Do NOT change AllowedExternalID and DatastreamerRoleARN.\ **5.** Set the *IAM Creation* checkbox.\ **6.** Execute the CFN Stack by clicking on *Create Stack*. ![cfn_s3_template.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/0138a7e-cfn_s3_template.png) **7.** Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![cfn_complete.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/a394239-cfn_complete.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_s3_cfn_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/67ecf11-aws_s3_cfn_cmp.png) After completing the steps, the selected record type should show up in the AWS S3 bucket. If there are any issues or problems with the setup, please feel free to contact our support. ## Kinesis - Integration With the Kinesis integration, Event and Usage Records from the 1NCE Data Streamer are directed to AWS Kinesis for real-time data analytics. ### Cloud Formation Setup - Kinesis To setup the 1NCE Data Streamer integration with AWS Kinesis, it is recommended to use the Cloud Formation Template provided in the 1NCE Connectivity Management Portal (CMP). As a reference the used Cloud Formation Template is provided on the 1NCE GitHub page. **1.** Open the CMP and navigate to *Configuration>Data Streams>Add New Data Stream*.\ **2.** In the popup select AWS Kinesis as *API Type* and select the desired *Stream Type*.\ **3.** Click on *Create IAM Role* to open the Cloud Formation Template in a separate window. ![aws_kinesis_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/7ae09fb-aws_kinesis_cmp.png) **4.** Adapt the CFN Template parameters (Stack Name, KinesisStreamName). Do NOT change AllowedExternalID and DatastreamerRoleARN.\ **5.** Set the *IAM Creation* checkbox.\ **6.** Execute the CFN Stack by clicking on *Create Stack*. ![aws_kinesis_cfn.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/d6f5e3a-aws_kinesis_cfn.png) **7.** Please wait until the Cloud Formation Process has ended and all resources have been created. Once the Cloud Formation Stack has successfully finished, please proceed with the following steps. ![aws_cfn_done.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/27f986f-aws_cfn_done.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. ![aws_kinesis_cfn_cmp.png](/img/platform-services/platform-services-data-streamer/data-streamer-setup-guides/4f535ec-aws_kinesis_cfn_cmp.png) **8.** Go to the *Outputs* tab of the created CFN Stack.\ **9.** Copy the shown parameters to the popup in the 1NCE CMP.\ **10.** Click on *Save* in the popup. The Data Streamer integration will be setup. Please not that this might take a few minutes. After completing the steps, the selected record type should show up in the AWS Kinesis Stream bucket. Please note that this may take some time and events/usage records need to be generated by the SIMs. If there are any issues or problems with the setup, please feel free to contact our support. --- # Usage Events Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-usage-events/ # Usage Events The 1NCE Data Streamer Service offers a stream of Usage Events. This chapter will focus on the Usage Event specification. In this chapter, the focus lies on the JSON Object format. For other integrations, the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used. ## Usage Event Triggers **Data Connection Events** — For an ongoing PDP data connection, at most, one event every 15 minutes if more than 100kB of data was used. This event contains the aggregated usage since the start of the PDP or since the last usage event. **Connection Closure Events** — One event on the closure of a PDP data connection. This event contains the usage since the last event or the entire aggregated usage if no prior event has been provided for the closed PDP data connection. **SMS Events** — For SMS a usage event is provided per individual MO-/MT-SMS send. The 1NCE Data Streamer provides two types of events for SMS and Data volume usage. ## Usage Events ### Data Usage Event Data Usage events are sent for every Endpoint while the Endpoint is consuming data service. The frequency of Data Usage events depends on platform configuration parameters e.g. an event every 5 minutes and/or every 1 megabyte consumed. ### SMS Usage Event SMS Usage events are sent for every Endpoint while the Endpoint is consuming SMS service. A SMS Usage event is sent for every MO SMS or MT SMS. If SMS submission was rejected by the platform e.g. due to exceeded quota or monthly limit, then the SMS will be not charged and hence no SMS Usage event will be emitted. ## Example Usage Events Let us start with a few Example Usage Events in the form of JSON Objects from the Data Streamer. Please note that some fields only include placeholder or example values.
Data Usage Event Example ```json { "id": 819948096, "operator": { "id": 78, "name": "Bite GSM", "mnc": "05", "country": { "id": 110, "mcc": "247", "name": "Latvia" } }, "organisation": { "id": 100018, "name": "81013181" }, "tariff": { "id": 369, "name": "MVP Phase 2 Tarriff", "ratezone": { "id": 4, "name": "T369.RZ1" } }, "traffic_type": { "id": 5, "description": "Data" }, "endpoint": { "id": 100000519, "name": "8988228066605682521", "ip_address": "10.0.1.118", "imei": "3556200910473501" }, "volume": { "total": 1.0049019, "rx": 1.0049019, "tx": 0 }, "sim": { "id": 10000299, "iccid": "8988228066605682521", "msisdn": "882285105682521" }, "start_timestamp": "2024-12-15T06:24:47.000Z", "end_timestamp": "2024-12-15T06:25:10.000Z", "imsi": "901405105682521", "imsi_id": 100000299, "detail": { "pdp_context": { "rat_type": 6, "ipcan_session_id": "e17b3179-04e0-40e8-b982-0d5f826cea6e" } } } ```
SMS Usage Event Example ```json { "id": 8884551, "start_timestamp": "2024-12-15T06:27:26Z", "end_timestamp": "2024-12-15T06:27:27Z", "organisation": { "id": 103820, "name": "81023262" }, "operator": { "id": 77, "name": "LMT", "mnc": "01", "country": { "id": 110, "mcc": "247", "name": "Latvia" } }, "tariff": { "id": 2703, "name": "Tariff 718916841", "ratezone": { "id": 11428, "name": "IoT Cloud Connect Complete" } }, "imsi": "901405301000216", "imsi_id": 100003437, "traffic_type": { "id": 6, "description": "SMS" }, "endpoint": { "id": 100001494, "name": "8988228530100000216", "imei": "8643510517167031", "ip_address": "10.0.0.1" }, "volume": { "total": 1, "rx": 0, "tx": 1 }, "sim": { "msisdn": "882285301000216", "iccid": "8988228530100000216", "id": 10003354 } } ```
## Usage Data Properties These are the main properties of a Usage Event that help to identify the endpoint and provide an insight into the volume used. | Property | Data Type | Description | | :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------ | | `id` | LONG (64-bit integer) | Unique ID for each Usage Event sent. Duplicate received event IDs indicate possible retransmissions. | | `cost` | DECIMAL(14,10) | Does not reflect the real world cost, 1:1 translation of usage. (Legacy field, may not be present in newer events) | | `currency` | JSON Object | Currency object with information about the cost currency. (Legacy field, may not be present in newer events) | | `start_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage start in the ISO 8601 format. | | `end_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage end in the ISO 8601 format. | | `volume` | JSON Object | Object with the exact volume used as part of the Usage Event. See [Volume](#volume-object) for more information. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Organization Object](#organisation-object) for more information. | | `operator` | JSON Object | Operator information, see [Operator Object](#operator-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM Object](#sim-object) for more information. | | `tariff` | JSON Object | Tariff details, see [Tariff Object](#tariff-object) for more information. | | `traffic_type` | JSON Object | Type of traffic of the Usage Event, see [Traffic Type Object](#traffic-type-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint Object](#endpoint-object) for more information. | | `detail` | JSON Object | Additional details specific to the usage type, see [Detail Object](#detail-object) for more information. | ## Object Specifications ### Currency Object The cost object is set as a 1:1 relation to the used volume. It does not reflect the real world cost. This is a legacy field and may not be present in newer usage events. | Property | Data Type | Description | | :------- | :---------------- | :--------------------------------------------------- | | `id` | INTEGER | Unique identifier of the currency of indicated cost. | | `symbol` | UTF-8 Char STRING | Symbol of the currency as UTF-8 Char. | | `code` | ISO 4217 STRING | Currency Code in ISO format. | ### Organisation Object Information about the organization of the SIM that generated the volume usage event. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of the organisation. | | `name` | STRING | 1NCE Customer ID. | ### SIM Object Details about the SIM that is responsible for the volume usage. | Property | Data Type | Description | | :------- | :-------- | :---------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | ### Operator Object Operator the SIM was attached to when the usage was generated. | Property | Data Type | Description | | :-------- | :---------- | :------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of visited operator. | | `mnc` | STRING | Mobile Network Code of the roaming operator. | | `name` | STRING | Name of the roaming mobile operator. | | `country` | JSON Object | Country information object, see [Country Object](#country-object) for more information. | ### Country Object Country of the device with the 1NCE SIM where the usage was generated. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------ | | `id` | INTEGER | Unique identifier of visited country. | | `mcc` | STRING | Mobile Country Code of the operator. | | `name` | STRING | Name of visited country. | ### Tariff Object Specific tariff assigned to the 1NCE SIM. | Property | Data Type | Description | | :--------- | :---------- | :---------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of applied tariff. | | `name` | STRING | Name of the applied tariff. | | `ratezone` | JSON Object | Ratezone information object, see [Ratezone Object](#ratezone-object) for more information. | ### Ratezone Object The ratezone in which the SIM generated the indicated usage. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of applied Ratezone. | | `name` | STRING | Name of the Ratezone. | ### Traffic Type Object Identifies what kind of traffic was used and is shown in the Usage Event. This could either be Data or SMS. | Property | Data Type | Description | | :------- | :-------- | :--------------------------------------------------- | | `id` | INTEGER | Unique identifier of traffic type. 5 = Data, 6 = SMS | | `name` | STRING | Name of traffic type either "Data" or "SMS". | ### Endpoint Object Details about the endpoint/device with the 1NCE SIM that generated the usage. | Property | Data Type | Description | | :----------- | :-------- | :------------------------------------------- | | `id` | INTEGER | Unique identifier of traffic type. | | `tags` | STRING | User-defined tags set for this endpoint. | | `ip_address` | STRING | The IP address assigned to this endpoint. | | `imei` | STRING | The IMEI of the endpoint hardware. | | `name` | STRING | The user-defined name set for this endpoint. | | `balance` | STRING | (Legacy field, may not be present) | ### Volume Object Exact volume, either data in MegaBytes or number of SMS used by the SIM. | Property | Data Type | Description | | :------- | :------------ | :--------------------------------------------------------------------------------------------------------------------------------- | | `total` | DECIMAL(14,6) | Total traffic consumed, sum of `tx` and `rx`. | | `tx` | DECIMAL(14,6) | **Dependent on Traffic Type:** Upstream traffic (MiB - Binary unit based) send by the endpoint. **or** Number of sent MO-SMS | | `rx` | DECIMAL(14,6) | **Dependent on Traffic Type:** Downstream traffic (MiB - Binary unit based) received by the endpoint. **or** Number of sent MT-SMS | ### Detail Object Additional details specific to the usage type. This object may contain different information depending on the type of usage event. **For Data Usage Events:** | Property | Data Type | Description | | :------------ | :---------- | :-------------------------------------------- | | `pdp_context` | JSON Object | PDP context information for data connections. | **PDP Context Object:** | Property | Data Type | Description | | :----------------- | :-------- | :------------------------------------------------- | | `rat_type` | INTEGER | Radio Access Technology type identifier. | | `ipcan_session_id` | STRING | IP-CAN session identifier for the data connection. | --- # Usage Records Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/data-streamer-usage-records/ The 1NCE Data Streamer Service offers a stream of Event and Usage Records. This chapter will focus on the Usage Record specification. In this chapter, the focus lies on the JSON Object format. For other integrations, the format might be different, but the data fields are comparable. Please refer to the setup of the offered integrations to get more information about the specific data formats used. Usage Records are triggered on SIM level and are based on the following rules: - For an ongoing PDP data connection, at most, one record every 15 minutes if more than 100kB of data was used. This record contains the aggregated usage since the start of the PDP or since the last usage record. - One record on the closure a PDP data connection. This record contains the usage since the last record or the entire aggregated usage if no prior record has been provided for the closed PDP data connection. - For SMS a usage record is provided per individual MO-/MT-SMS send. In the following, the two types of Usage Records and the included data fields will be shown. The 1NCE Data Streamer provides two types of records for SMS and Data volume usage. *** ## Example Usage Records Let us start with a few Example Usage Records in the form of JSON Objects from the Data Streamer. Please note that some fields only include placeholder or example values.
05_Data_Usage_Record ```json 05_Data_Usage_Record.json { "imsi": "", "organisation": { "name": "8100xxxx", "id": 1234 }, "start_timestamp": "2021-08-09T12:59:05Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "id": 2, "name": "T-Mobile", "mnc": "01", "country": { "id": 74, "mcc": "262", "name": "Germany" } }, "tariff": { "ratezone": { "name": "Rate Zone 2 (EU - DE)", "id": 2067 }, "name": "1NCE Production 01", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "Data", "id": 5 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "id": 12345678, "balance": null }, "cost": 0.001176, "volume": { "total": 0.001176, "tx": 0.001176, "rx": 0.0 } } ```
06_SMS_Usage_Record ```json 06_SMS_Usage_Record.json { "imsi": "", "organisation": { "name": "8100xxxx", "id": 12345 }, "start_timestamp": "2021-08-09T12:51:20Z", "sim": { "msisdn": "", "iccid": "", "id": 123456, "production_date": "2018-04-17T15:01:50Z" }, "currency": { "id": 1, "symbol": "€", "code": "EUR" }, "operator": { "mnc": "01", "name": "T-Mobile", "country": { "name": "Germany", "id": 74, "mcc": "262" }, "id": 5 }, "tariff": { "ratezone": { "name": "Zone 1", "id": 2067 }, "name": "Tariff 1", "id": 398 }, "imsi_id": 1234567, "traffic_type": { "description": "SMS", "id": 6 }, "id": 1234567890, "end_timestamp": "2021-08-09T12:51:20Z", "endpoint": { "tags": null, "ip_address": "", "name": "", "imei": "", "balance": null, "id": 1234567 }, "cost": 1.0, "volume": { "total": 1.0, "tx": 0.0, "rx": 1.0 } } ```
*** ## Usage Data Properties These are the main properties of a Usage Record that help to identify the endpoint and provide an insight into the volume used. | Property | Data Type | Description | | :---------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------ | | `id` | LONG (64-bit integer) | Unique ID for each Usage Record sent. Duplicate received event IDs indicate possible retransmissions. | | `cost` | DECIMAL(14,10) | Does not reflect the real world cost, 1:1 translation of usage. | | `currency` | JSON Object | Currency object with information about the cost currency. See [Cost](#cost-object) for more information. | | `start_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage start in the ISO 8601 format. | | `end_timestamp` | TIMESTAMP (UTC) | Timestamp with date and time of the usage end in the ISO 8601 format. | | `volume` | JSON Object | Object with the exact volume used as part of the Usage Record. See [Volume](#volume-object) for more information. | | `imsi` | STRING | The International Mobile Subscriber Identity as String. | | `organisation` | JSON Object | Object with the ID and the name of the organization. See [Event Organization](#organization-object) for more information. | | `operator` | JSON Object | Operator information, see [Operator](#operator-object) for more information. | | `sim` | JSON Object | Subscriber Identification Module, see [SIM](#sim-object) for more information. | | `tariff` | JSON Object | Tariff details, see [Tariff](#tariff-object) for more information. | | `traffic_type` | JSON Object | Type of traffic of the Usage Record, see [Traffic Type](#traffic-type-object) for more information. | | `endpoint` | JSON Object | Endpoint/Device information object, see [Endpoint](#endpoint-object) for more information. | *** ## Cost Object The cost object is set as a 1:1 relation to the used volume. It does not reflect the real world cost. | Property | Data Type | Description | | :------- | :---------------- | :--------------------------------------------------- | | `id` | INTEGER | Unique identifier of the currency of indicated cost. | | `symbol` | UTF-8 Char STRING | Symbol of the currency as UTF-8 Char. | | `code` | ISO 4217 STRING | Currency Code in ISO format. | *** ## Organisation Object {#organization-object} Information about the organization of the SIM that generated the volume usage record. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of the organisation. | | `name` | STRING | 1NCE Customer ID. | *** ## SIM Object Details about the SIM that is responsible for the volume usage. | Property | Data Type | Description | | :---------------- | :-------------- | :---------------------------------------------------------- | | `id` | INTEGER | Unique ID of the SIM. | | `iccid` | STRING | Integrated Circuit Card Identifier of the SIM. | | `msisdn` | STRING | Mobile Subscriber ISDN of the SIM Card. | | `production_date` | TIMESTAMP (UTC) | Timestamp when the SIM was produced in the ISO 8601 format. | *** ## Operator Object Operator the SIM was attached to when the usage was generated. | Property | Data Type | Description | | :-------- | :---------- | :------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of visited operator. | | `mnc` | STRING | Mobile Network Code of the roaming operator. | | `name` | STRING | Name of the roaming mobile operator. | | `country` | JSON Object | Country information object, see [Country](#country-object) for more information. | *** ## Country Object Country of the device with the 1NCE SIM where the usage was generated. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------ | | `id` | INTEGER | Unique identifier of visited country. | | `mcc` | STRING | Mobile Country Code of the operator. | | `name` | STRING | Name of visited country. | *** ## Tariff Object Specific tariff assigned to the 1NCE SIM. | Property | Data Type | Description | | :--------- | :---------- | :----------------------------------------------------------------------------------- | | `id` | INTEGER | Unique identifier of applied tariff. | | `name` | STRING | Name of the applied tariff. | | `ratezone` | JSON Object | Ratezone information object, see [Ratezone ](#ratezone-object) for more information. | *** ## Ratezone Object The ratezone in which the SIM generated the indicated usage. | Property | Data Type | Description | | :------- | :-------- | :------------------------------------- | | `id` | INTEGER | Unique identifier of applied Ratezone. | | `name` | STRING | Name of the Ratezone. | *** ## Traffic Type Object Identifies what kind of traffic was used and is shown in the Usage Record. This could either be Data or SMS.
Property Data Type Description

id

INTEGER

Unique identifier of traffic type. 5 = Data 6 = SMS

name

STRING

Name of traffic type either "Data" or "SMS".
*** ## Endpoint Object Details about the endpoint/device with the 1NCE SIM that generated the usage. | Property | Data Type | Description | | :----------- | :-------- | :------------------------------------------- | | `id` | INTEGER | Unique identifier of traffic type. | | `tags` | STRING | User-defined tags set for this endpoint. | | `ip_address` | STRING | The IP address assigned to this endpoint. | | `imei` | STRING | The IMEI of the endpoint hardware. | | `name` | STRING | The user-defined name set for this endpoint. | | `balance` | STRING | | *** ## Volume Object Exact volume, either data in MegaBytes or number of SMS used by the SIM.
Property Data Type Description

total

DECIMAL(14,6)

Total traffic consumed, sum of tx and rx.

tx

DECIMAL(14,6)

Dependent on Traffic Type: Upstream traffic (MB) send by the endpoint. or Number of sent MO-SMS

rx

DECIMAL(14,6)

Dependent on Traffic Type: Downstream traffic (MB) received by the endpoint. or Number of sent MT-SMS
--- # SMS Events Source: https://help.1nce.com/docs/v2/platform-services/platform-services-data-streamer/sms-records/ # SMS Events The 1NCE Data Streamer Service provides real-time SMS Events that give you detailed insights into SMS traffic for your IoT devices. This chapter focuses on the two types of SMS Events supported by the platform. ## SMS Event Types **SMS MT DLR** — MT (Mobile Terminated) Delivery Reports provide status updates for SMS messages sent to devices, including delivery confirmations, failures, and expiry notifications. **SMS MO** — MO (Mobile Originated) events represent SMS messages sent from mobile devices to your specified interfaces or applications. ## Event Specifications ### SMS MT DLR (Delivery Report) SMS MT Delivery Reports are generated when SMS messages sent to devices reach a final state. These events provide delivery status information including successful delivery, failures, or expiration. **Supported Status Types:** - `DELIVERED`: Message successfully delivered to the device - `FAILED`: Message delivery failed - `EXPIRED`: Message expired before delivery
SMS MT DLR Example ```json { "id": 8891889, "submit_date": "2024-12-15T16:55:31Z", "final_date": "2024-12-15T16:55:35Z", "organisation": { "id": 103820 }, "endpoint": { "id": 100001494, "name": "8988228530100000216" }, "status": { "status": "DELIVERED", "id": 4 }, "detail": { "sms": { "id": "551734281731175386" } } } ```
### SMS MO (Mobile Originated) SMS MO events represent messages sent from mobile devices to your customer-specified interfaces. These events capture the complete SMS content and routing information.
SMS MO Example ```json { "id": 8901947, "submit_date": "2024-12-16 07:01:00", "pid": 0, "organisation": { "id": 103820 }, "dest_address": "338", "source_address": "882285301000216", "dcs": 0, "payload": "34178d09-905a-4289-95b6-da61f966d3e1;1734332456", "endpoint": { "id": 100001494, "name": "8988228530100000216" } } ```
## SMS Event Properties ### Common Properties Properties shared across both SMS event types: | Property | Data Type | Description | | :------------- | :-------------------- | :--------------------------------------------------------- | | `id` | LONG (64-bit integer) | Unique identifier for each SMS event | | `submit_date` | TIMESTAMP (UTC) | Timestamp when the SMS was submitted in ISO 8601 format | | `organisation` | JSON Object | Organization information containing the organization ID | | `endpoint` | JSON Object | Endpoint information including ID and name (typically ICCID) | ### SMS MT DLR Properties Specific properties for MT Delivery Report events: | Property | Data Type | Description | | :------------ | :-------------- | :---------------------------------------------------- | | `final_date` | TIMESTAMP (UTC) | Timestamp when the final delivery status was reached | | `status` | JSON Object | Delivery status information | | `detail` | JSON Object | Additional details including original SMS ID | **Status Object:** - `status`: String value (`DELIVERED`, `FAILED`, `EXPIRED`) - `id`: Numeric status identifier (4 = DELIVERED, 5 = FAILED, 6 = EXPIRED) ### SMS MO Properties Specific properties for Mobile Originated SMS events: | Property | Data Type | Description | | :--------------- | :-------- | :------------------------------------------------- | | `dest_address` | STRING | Destination address where the SMS was sent | | `source_address` | STRING | Source address (typically the device's MSISDN) | | `payload` | STRING | The actual SMS message content | | `dcs` | INTEGER | Data Coding Scheme (0 = default GSM 7-bit) | | `pid` | INTEGER | Protocol Identifier (0 = default) | ## Object Details ### Organisation Object Contains information about the customer organization: | Property | Data Type | Description | | :------- | :-------- | :------------------------------ | | `id` | INTEGER | Unique 1NCE customer organization identifier | ### Endpoint Object Represents the device/SIM endpoint: | Property | Data Type | Description | | :------- | :-------- | :--------------------------------------------- | | `id` | INTEGER | Unique endpoint identifier | | `name` | STRING | Endpoint name (typically the ICCID) | ### Detail Object (SMS MT DLR) Contains additional information specific to delivery reports: | Property | Data Type | Description | | :------- | :---------- | :----------------------------------- | | `sms` | JSON Object | Contains the original SMS identifier | **SMS Detail Object:** - `id`: Original SMS message identifier for correlation ## Integration Notes - SMS Events are delivered in real-time through the 1NCE Data Streamer - Each event includes a unique ID to handle potential retransmissions - Timestamps are provided in UTC format following ISO 8601 standard - Status codes are consistent across the platform for reliable processing --- # SIM Knowledge Source: https://help.1nce.com/docs/v2/sim-cards/sim-cards-knowledge/ Many associate a tiny piece of plastic, which has an embedded chip, with the term SIM card. A chip that is inserted into a mobile phone or other modem to allow a specific device to connect to some sort of mobile network for internet and messaging connectivity. As usual, there is more than meets the eye when it comes to the details of a SIM. From a basic point of view, a Subscriber Identity Module (SIM) is an Integrated Circuit (IC) with a Card Operating System (COS) which stores security features used to authenticate the subscriber devices in a mobile network.
![Developer_Hub_SIM_Cards.png](/img/sim-cards/sim-cards-knowledge/0b742fa-sim.png)
*Overview of the different 1NCE IoT SIM form factors.* This data includes a unique serial number (ICCID), International Mobile Subscriber Identity (IMSI), security authentication, and ciphering information to authenticate the SIM as a valid subscriber to a mobile network. Further, temporary local network information, access service list, Personal Identification Number (PIN), and a Personal Unblocking Key (PUK) is stored on a SIM. The following sections will cover the basics of some SIM parameters that show up as part of the 1NCE Services. It is important to understand their role in the 1NCE ecosystem, as these parameters are useful for general information, device identification, troubleshooting and security. *** # Personal Identification Number (PIN) All 1NCE SIM cards are preassigned a 6-digit Personal Identification Number (PIN), which is disabled by default. The SIM cards are ready to use and no PIN validation needs to take place because of it. For devices controlled by AT-Commands, it is a good idea to use the general AT-Command 'AT+CPIN?' to test if the 1NCE SIM card is ready for operation. This tests if the SIM card is ready for operation when booting up a modem with a 1NCE SIM inserted. The AT-Command should return 'READY', indicating that the SIM is recognized and ready for operation. *** # Integrated Circuit Card Identifier (ICCID) SIM cards are mainly identified by their Integrated Circuit Card Identifier (ICCID), an identifier of the actual SIM card chip itself. ICCIDs are also used to identify embedded SIM (eSIM) profiles. This ID can be up to 23 digits long, including a check digit calculated using the Luhn algorithm. The ICCID conforms to the ITU E.118 numbering standard. Note that an extra digit is sometimes returned using AT-Commands, but this is not an official part of the ICCID. The ICCID is used throughout the 1NCE ecosystem (1NCE Portal, API, Data Streamer, etc.) as a common parameter to identify each SIM provided by 1NCE. The following table shows the structural components of the ICCID for 1NCE SIMs.
Component Length & Example
ICCID Integrated Circuit Card Identifier 16 - 23 Digits: 89 88 280 666xxxxxxxx x 89 88 228 0666xxxxxxx x
IIN Issuer Identification Number 4 - 9 Digits: 89 88 228 89 88 280
  MII Major Industry Identifier 2 Digits: 89 - Telecommunications
  CC Country Code 1 - 3 Digits: 88 - No Geolocation (IoT Application)
  II Issuer Identifier 1 - 4 Digits: 228 - 1NCE 280 - 1NCE
SIM - ID ID Number 11 - 13 Digits: 666xxxxxxxx 0666xxxxxxx
C Checksum 1 Digit: x - Luhn Algorithm
*** # International Mobile Subscriber Identity (IMSI) The International Mobile Subscriber Identity (IMSI) identifies SIM cards uniquely by their individual operator in a cellular network. The IMSI is stored as a 64-bit field and is communicated to the connected cellular network. In the core of a mobile operator network, the IMSI is used as main identification for obtaining further customer and device specific data. The IMSI is used across all global mobile networks. The IMSI conforms to the ITU E.212 numbering standard. Not to confuse the IMSI with the ICCID, the ICCID is the id of the physical SIM, while the IMSI is part of a profile placed on the SIM. In the 1NCE ecosystem, the IMSI is often found alongside the ICCID. The following table shows the structural components of the IMSI for 1NCE SIMs.
Component Length & Example
IMSI International Mobile Subscriber Identity 13 - 15 Digits: 901 40 51000xxxxx
  MCC Mobile Country Code 3 Digits: 901 - Worldwide Shared Mobile Country Code 454 - Hong Kong
  MSISN Mobile Subscriber ISDN Number 8 - 9 Digits: 51000xxxxx - Mobile Subscriber ISDN Number
## MCC and MNC The Mobile Country Code (MCC) and Mobile Network Code (MNC) identify a country of domicile and a operator of that network in this country. Both together result in the Public Land Mobile Network (PLMN) code of the mobile subscriber. Since the 1NCE SIM cards are not bound to a real country or network these values are defined as: MCC-901 and MNC-40. The MCC-901 has a special meaning, i.e. this is a shared Mobile Country Code which is used worldwide instead of identifying a certain country. Hence, 1NCE as IoT-MNO has reserved the PLMN 901-40 for their purposes and uses it for the standard 1NCE product. *** # Mobile Station International Subscriber Directory Number (MSISDN) The Mobile Station International Subscriber Directory Number (MSISDN) is used together with the IMSI to uniquely identify a SIM subscription in the global mobile network. A normal non-IoT carrier uses the MSISDN for routing voice calls to a subscribed SIM. While the IMSI for a specific profile on a SIM does not change over time, the MSISDN can change. The MSISDN format is defined in the ITU-T E.164. In the 1NCE ecosystem, the MSISDN can be found in the detail properties of a SIM using the API or Data Streamer Service. Compared to the ICCID, IMSI or IMEI, the MSISDN plays less of an important role for the 1NCE IoT use cases. *** # International Mobile Equipment Identity (IMEI) Certain parameters reported in the 1NCE ecosystem are not sourced from the 1NCE SIM but rather relate to the specific device used in conjunction with the SIM card. Such a parameter is the International Mobile Equipment Identity (IMEI). It is a unique number for the identification of a mobile SIM device modem. Each standardized modem that uses any type of SIM to connect to a mobile network operator has a unique IMEI. The IMEI, 15 digits: 14 + check digit, or IMEISV, 16 digits: 14 + two (software version), consists of information on the origin, model, and serial number of the device. The structure of the IMEI/SV is specified in 3GPP TS 23.003. In the 1NCE ecosystem, the IMEI/SV is used to identify individual devices and manufacturers. In the 1NCE Data Streamer and API, the IMEI/SV for some roaming operators might have an additional 'f' at the end of the IMEI.
Component Length & Example
IMEI International Mobile Equipment Identity 15 - 16 Digits: 86 995103 xxxxxx x - IMEI 86 995103 xxxxxx xx - IMEISV
  TAC Type Allocation Code 8 Digits: 86 995103 - Example of SIM 7000G
  SNR Serial Number 6 Digits: xxxxxx - Unique per Device
  CD/SVN Check Digit or Software Version 1 - 2 Digits: x - Check Digit xx - Software Version Number
## IMEI Lock Each device in a mobile network has an IMEI number which identifies the hardware uniquely when connecting to a network. 1NCE offers the functionality to lock a given device to the SIM card using the IMEI. If the IMEI lock is enabled during an active PDP data session, the current session will be dropped and the device forced to reconnect instantly. This ensures that the currently in use device is locked to the SIM and there is no possibility to change the SIM to another device after enabling the IMEI lock feature. Once the IMEI Lock option is enabled, the network will link the IMEI to the specific SIM card. Subsequent connection attempts with this SIM card using another device with different IMEI are blocked. This feature can be disabled and enabled by the customer for each SIM card individually either via the 1NCE Portal or 1NCE API. For the IMEI Lock functionality the IMEISV is used. The IMEISV is derived by the IMEI and includes the additional software version parameter. --- # 1NCE IoT SIMs Source: https://help.1nce.com/docs/v2/sim-cards/sim-cards-overview/ 1NCE offers a range of IoT SIMs to meet different customer needs, shown in the following image.
![1NCE Standard SIMs compared to 1NCE eUICC SIMs](/img/sim-cards/sim-cards-overview/32d7638-Freedom_to_switch.webp)
*IoT SIMs provided by 1NCE* # IoT SIM Card Business This is a 3-in-1 plastic SIM card used for our 1NCE IoT Lifetime Flat. This SIM is best suited for off-the-shelve, ready-to-use IoT devices. It easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features makes the 1NCE IoT SIM Card Business ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. It does not support the Freedom to Switch feature (eUICC).
![](/img/sim-cards/sim-cards-overview/5785ebf-cliu9g5y5003i0rqmejpnayyt-sim-card.max.png)
# IoT SIM Card Industrial This SIM has all the same capabilities of the IoT SIM Card Business but comes with **Freedom to Switch** (eUICC feature) which enables to change the SIM profile in the future.
![](/img/sim-cards/sim-cards-overview/7882db0-SIM_industrial.png)
# IoT SIM Chip Industrial The IoT SIM Chip is identical to the IoT SIM Card with the **Freedom to Switch** eUICC feature, but comes in the MFF2 form factor. The IoT SIM Chip Industrial form factor is optimized for typical IoT device environments factors like heavy vibration and higher temperature ranges but also increased security. 1NCE recommends the integration of IoT SIMs Chip Industrial in custom-developed IoT devices and use cases where strong environmental robustness is needed.
![](/img/sim-cards/sim-cards-overview/c1c6c6d-chip.png)
--- # IoT SIM Card Business Source: https://help.1nce.com/docs/v2/sim-cards/sim-cards-overview/sim-cards-iot-business/ Although the first, traditional plastic-backed SIM cards were introduced to the mobile network market over 30 years ago, the adapted form factor and technical specifications still apply today as a major key for mobile network communication. As part of the 1NCE connectivity services, the plastic 3in1 IoT SIM Card Business offers the fundamental entrance to the world of mobile IoT communication. This section will cover the basics about the physical IoT SIM Card Business form factor, technical specifications as well as recommendations for IoT hardware application cases.
![Overview of the 1NCE 3in1 IoT SIM Card Business, which includes the 2FF, 3FF and 4FF form factors.](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/613cd18-cliu9g5y5003i0rqmejpnayyt-sim-card.max.png)
*** # SIM Form Factor Over the years, with the hardware miniaturization and especially IoT use cases for mobile networks, the physical SIM Card format was adapted multiple times to make the overall footprint smaller. As the SIM chip design and layout was retained to provide backwards combability, the surrounding plastic format was changed. As a result, four common SIM Card form factors (1-4 FF) were established. Original full-size SIM Cards (1FF) had the typical credit card form factor. As this standard is used only rarely today, it has been phased out of production. The remainder 2FF, 3FF and 4FF are still commonly used and sold as 3in1 breakout, plastic-backed SIM Cards. The four SIM Card form factors are specified in ETSI TS 102 221. The exact dimension specifications of the form factors are listed in the table below. | | 2FF - Mini SIM | 3FF - Micro SIM | 4FF - Nano SIM | | :------------ | :------------- | :-------------- | :----------------------- | | **Height** | 25mm | 15mm | 12.3mm ± 0.1 mm | | **Width** | 15mm | 12mm | 8.8mm | | **Thickness** | 0.76mm | 0.76mm | 0.67mm +0.03 mm/-0.07 mm | 1NCE IoT SIM Card Business are 3in1 plastic-backed SIMs which incorporate the standardized 2FF Mini, 3FF Micro and 4FF Nano form factors. The 1NCE SIMs are shipped in a half-size carrier to make handling and shipping of the breakout SIMs easier. Depending on the customer needs the IoT SIM Card Business can be carefully broken down into the needed form factor and also reassembled back up to 2FF Mini with the supplied adapters.
![1NCE_4FF_SIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/20aeb83-1NCE_4FF_SIM_Dimensions.png)
*1NCE IoT SIM Card Business 4FF reference dimensions and pin assignment as of ETSI TS 102 221.* As 4FF is the smallest form factor that minimizes the plastic-backed SIM Card to the bare IC, we will use it as reference for the pinout. The pinout is the same for all IoT SIM Card Businesses as the SIM IC is identical. Shown above is the pinout reference and dimensions of the 4FF SIM according to ETSI TS 102 221. While the 1NCE IoT SIM Card Business 4FF and IoT SIM Chip Industrial form factor are different, the pinout of the actual ICs are the same. The pinout table references the pinout of the dimensional reference figure for the 4FF SIM Card.
Contact Pin Spec. Description 1NCE IoT SIM Card Business Pinout

C1

VCC Supply Voltage

VCC

C2

RST Reset Pin

RST

C3

CLK Clock Signal

CLK

C4 and C8

Optional USB interface according to ETSI TS 102 600

N/A

C5

GND Ground Connection

GND

C6

VPP Programming Voltage

N/A

C7

I/O Input Output Data

I/O
*** # Shipping & Assembly Packaging 1NCE 3in1 IoT SIM Card Business Cards are packaged in a half-size breakout card to save on plastic wastage. This makes handling and shipping of the different SIM form factors easier. Each of these breakout cards, shown below, contains one 3in1 SIM. For easier identification, a barcode and numerical representation of the EAN code and the ICCID are printed on the back of the cards. When ordering low quantities of IoT SIM Card Business, the cards will be packaged and shipped in small plastic wrapped packages. For larger orders will be fulfilled by shipping boxes of 100 or 500 SIMs respectively. These boxes are packaged in sequence, lowest to highest ICCID with a label sticker indicating the first and last ICCID of the box.
![1NCE_FlexSIM.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-business/a2dce8795d72eda003b894480f74b2ca4184cc2a229c63e32e0fc2a1dbf7baab-SIMCBusiness.png)
*1NCE 3in1 IoT SIM Card Business inside the half-size breakout card used for easier shipping and packaging.* *** # SIM ICCID Identification Each SIM Card can be uniquely identified by the ICCID. This SIM identification is used throughout the 1NCE ecosystem to mark each unique SIM. The ICCID can be read by the hardware modem using an AT-Command or manufacturer specific request. For easier physical identification, each 1NCE IoT SIM Card Business has the ICCID of the particular SIM printed on the 4FF physical chip card. *** # IoT SIM Card Business Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIM Card Business comply with these technical standard specifications. Besides the key standard compliances, SIM Cards are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Card Business specifications that are relevant for the deployment of the 1NCE IoT SIM Card Business. Furthermore, references to the key standard compliances for the SIM interfaces are referenced.
Parameter 1NCE IoT SIM Card Business (3in1)
Form Factors (FF) 2FF - Mini, 3FF - Micro, 4FF - Nano
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -25°C to +85°C
Operating Voltages Class A, B and C (1.8V –5.0V ±10%)
Data Retention Period min. 10 years
Read/Write Cycles min. 500 000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # IoT SIM Card Business Application Cases As the plastic-backed IoT SIM Card Business remains the most commonly used form factor in the mobile communication field, this SIM serves as the ideal general-purpose solution for most off-the-shelf, ready-to-use IoT devices. The 3in1 form factor of the 1NCE IoT SIM Card Business is compatible with a wide range of devices which accept this standardized form factor. This form factor of SIM is easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features make the 1NCE IoT SIM Card Business ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. For any open questions about the detailed 1NCE IoT SIM Card Business product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # IoT SIM Card Industrial Source: https://help.1nce.com/docs/v2/sim-cards/sim-cards-overview/sim-cards-iot-industrial/ The form factor of the IoT SIM Card Industrial is identical to the IoT SIM Card Business with the plastic 3in1 format. The main differences are within the SIM chip, software and environmental ruggedness of the SIM card. This section will cover the basics about the physical IoT SIM Cards Industrial form factor, technical specifications as well as recommendations for IoT hardware application cases.
![Overview of the 1NCE 3in1 IoT SIM Cards Industrial, which includes the 2FF, 3FF and 4FF form factors. ](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/e7a6860-SIM_industrial.png)
*** # IoT SIM Cards Industrial Form Factor Over the years, with the hardware miniaturization and especially IoT use cases for mobile networks, the physical SIM Card format was adapted multiple times to make the overall footprint smaller. As the IoT SIM Chip Industrial design and layout was retained to provide backwards combability, the surrounding plastic format was changed. As a result, four common IoT SIM Cards Industrial form factors (1-4 FF) were established. Original full-size IoT SIM Cards Industrial (1FF) had the typical credit card form factor. As this standard is used only rarely today, it has been phased out of production. The remainder 2FF, 3FF and 4FF are still commonly used and sold as 3in1 breakout, plastic-backed SIM Cards. The four IoT SIM Cards Industrial form factors are specified in ETSI TS 102 221. The exact dimension specifications of the form factors are listed in the table below. | | 2FF - Mini SIM | 3FF - Micro SIM | 4FF - Nano SIM | | :------------ | :------------- | :-------------- | :----------------------- | | **Height** | 25mm | 15mm | 12.3mm ± 0.1 mm | | **Width** | 15mm | 12mm | 8.8mm | | **Thickness** | 0.76mm | 0.76mm | 0.67mm +0.03 mm/-0.07 mm | 1NCE IoT SIM Cards Industrial are 3in1 plastic-backed SIMs which incorporate the standardized 2FF Mini, 3FF Micro and 4FF Nano form factors. The 1NCE IoT SIM Cards Industrial are shipped in a half-size carrier to make handling and shipping of the breakout SIMs easier. Depending on the customer needs the IoT SIM Cards Industrial can be carefully broken down into the needed form factor and also reassembled back up to 2FF Mini with the supplied adapters.
![1NCE_4FF_SIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/20aeb83-1NCE_4FF_SIM_Dimensions.png)
*1NCE IoT SIM Cards Industrial 4FF reference dimensions and pin assignment as of ETSI TS 102 221.* As 4FF is the smallest form factor that minimizes the plastic-backed SIM Card to the bare IC, we will use it as reference for the pinout. The pinout is the same for all IoT SIM Cards Industrial as the SIM IC is identical. Shown above is the pinout reference and dimensions of the 4FF SIM according to ETSI TS 102 221. While the 1NCE IoT SIM Cards 4FF and eSIM MFF2 form factor are different, the pinout of the actual ICs are the same. The pinout table references the pinout of the dimensional reference figure for the 4FF IoT SIM Cards Industrial.
Contact Pin Spec. Description 1NCE IoT SIM Cards Industrial Pinout

C1

VCC Supply Voltage

VCC

C2

RST Reset Pin

RST

C3

CLK Clock Signal

CLK

C4 and C8

Optional USB interface according to ETSI TS 102 600

N/A

C5

GND Ground Connection

GND

C6

VPP Programming Voltage

N/A

C7

I/O Input Output Data

I/O
*** # Shipping & Assembly Packaging 1NCE 3in1 IoT SIM Cards Industrial are packaged in a half-size breakout card to save on plastic wastage. This makes handling and shipping of the different SIM form factors easier. Each of these breakout cards, shown below, contains one 3in1 SIM. For easier identification, on the back of the cards a barcode and numerical representation of the EAN code and the ICCID is printed. When ordering low quantities of IoT SIM Cards Industrial, the cards will be packaged and shipped in small plastic-wrapped packages. For larger orders will be fulfilled by shipping boxes of 100 or 500 SIMs respectively. These boxes are packaged in sequence, lowest to highest ICCID with a label sticker indicating the first and last ICCID of the box.
![1NCE_FlexSIM.png](/img/sim-cards/sim-cards-overview/sim-cards-iot-industrial/dd1d47b257ed4b77c15c798869af49d8c7b6912c34ff71810aa6754e0bbcaf19-SIMCIndustrial.png)
*1NCE 3in1 IoT SIM Cards inside the half-size breakout card used for easier shipping and packaging.* *** # IoT SIM Cards Industrial eID Identification An eID is a 32-digit global unique identifier number, containing information that uniquely identifies the physical SIM. Using the eUICC feature, the eID is the most important number to identify the SIM as the ICCID may change with the active profile. The eID is unique to the IoT SIM, and will remain always the same. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM Card Industrial has the eID of the particular SIM printed on the 4FF physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # IoT SIM Cards Industrial Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIM Cards Industrial complies with these technical standard specifications. Besides the key standard compliances, SIM Cards are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Cards Industrial specifications that are relevant for the deployment of the 1NCE IoT SIM Cards Industrial. Furthermore, references to the key standard compliances for the SIM interfaces are listed.
Parameter 1NCE IoT SIM Card Industrial (3in1)
Form Factors (FF) 2FF - Mini, 3FF - Micro, 4FF - Nano
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -40°C to +105°C
Operating Voltages Class A, B and C (1.62V – 5.5V)
Data Retention Period min. 10 years
Number of profiles max. 10
Read/Write Cycles min. 2.000.000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # IoT SIM Cards Industrial Application Cases As the plastic-backed IoT SIM Cards Industrial is currently still the most commonly used form factor in the mobile communication field, it is best suited as a general-purpose SIM for most off-the-shelve, ready-to-use IoT devices. The 3in1 form factor of the 1NCE IoT SIM Cards Industrial is compatible with a wide range of devices that accept this standardized form factor. This form factor of SIM is easy to install, exchange, swappable between devices and ready for the IoT production environment. These key features make the 1NCE IoT SIM Cards Industrial ideal for every stage of the IoT device life cycle, from early, flexible prototyping to deploying thousands of devices in the field. Also, 1NCE IoT SIM Cards Industrial are ideal for more demanding environments due to their enhanched physical attributes, for example, operating temperature. For any open questions about the detailed 1NCE IoT SIM Cards Industrial product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # IoT SIM Chip Industrial Source: https://help.1nce.com/docs/v2/sim-cards/sim-cards-overview/sim-chips-iot-industrial/ The traditional plastic-backed SIM originated from the user equipment (UE) usage for telecommunication where customers needed to exchange SIMs easily as the devices were not bound to a particular SIM. Starting in 2016, the embedded SIM (eSIM) or embedded Universal Integrated Circuit Card (eUICC) gained interest from developers due to its smaller footprint and deeper integration possibilities. Especially in custom embedded Machine-to-Machine (M2M) and IoT hardware application cases, the IoT SIM Chip Industrial offers unique advantages compared to the traditional IoT SIM Card Business. In purpose-built IoT devices, there is no need for regular manual SIM Card swaps. Key factors like ruggedness, security and space constraints have high priority. For these special needs, the 1NCE IoT SIMs Chip Industrial provides the ideal solution. This section covers the 1NCE IoT SIM Chip Industrial product with its standardized form factor, technology specifications and outline recommended application cases.
![1NCE IoT SIM Chip Industrial MFF2 Integrated Circuit.](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/974e330-chip.png)
*** # IoT SIM Chip Industrial Form Factor As the IoT SIM Chip Industrial evolved from the traditional IoT SIM Card Business, it shares the same technological functionality but just in a smaller physical packaged form factor. The IoT SIM Chip Industrial format is commonly designated as MFF2. The 1NCE IoT SIM Chip Industrial conforms to this MFF2 footprint in a Quad-Flat No-Leads 8 (QFN8) Integrated Circuit (IC) package. The MFF2 package is specified in ETSI 102 671. The QFN8 IoT SIM Chip Industrial package is not mounted inside a socketed adapter like the IoT SIM Card Business, it is designed to be directly soldered to the Printed Circuit Board (PCB) of a device. QFN8 is an often used footprint in electronic devices. Thus, it can be easily integrated into automated assembly production lines of IoT-enabled devices. The specifications of the form factor are shown in the figure below.
![1NCE_eSIM_Dimensions.png](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/8f83e1d-1NCE_eSIM_Dimensions.png)
Embedded-SIMs share the same basic pinout as IoT SIMs Card Business but in a different form factor shown in the figure above. The following table references the pin assignments and lists their respective functional pinout. | Contact Pin | Spec. Description | 1NCE IoT SIM Chip Industrial Pinout | | --- | --- | --- | | C1 | **VCC** Supply Voltage | VCC | | C2 | **RST** Reset Pin | RST | | C3 | **CLK** Clock Signal | CLK | | C4 and C8 | **Optional** USB interface according to ETSI TS 102 600 | N/A | | C5 | **GND** Ground Connection | GND | | C6 | **VPP** Programming Voltage | N/A | | C7 | **I/O** Input Output Data | I/O | *** # Shipping & Assembly Packaging When ordering 1NCE IoT SIMs Chip Industrial, the QFN8 ICs are packaged in a standardized tape reel of 100, 500, 1000, 2500, and 3000 IoT SIMs Chip Industrial. These tape reels can be directly used in an automated production assembly line. 1NCE IoT SIMs Chip Industrial are packaged in 12mm wide tape, which is 1.2mm thick and covered with a plastic film to keep the IoT SIM Chip Industrial ICs in place until production. The packing process and materials meet the requirements defined in JEDEC J-STD-033 with ESD precautions and proper handling procedures. The tape is provided on 7-inch (178mm) and 13-inch (330mm) reels. For lots of 100 or 500 IoT SIMs Chip Industrial, 7-inch reels are used and for 1000, 2500 or 3000 IoT SIMs Chip Industrial 13-inch reels are used. **Package outline** ![](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/948f33a84761c2c4213387a79b00b93ada17bd9f27b427c05946effbe0481ca9-image.png) **Package Footprint** ![](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/7b3b41cd125600e0c8d6df30071c4aef89fcb9c1fa54cc4c86b4004f10c08a3e-image.png) **Tape & Reel packing** ![Infineon Integration Guide SLx16 SLx17](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/9fb616e62a74da6e4531c348a40b45daff2e61201909b0af1c8fc4f0b1db682a-image.png) Each reel is vacuum packaged separately with a humidity indicator card, desiccant and a barcode label in a reel cardboard box. The barcode label shows the first and last IoT SIM Chip Industrial ICCID of the specific reel. IoT SIMs Chip Industrial are produced in sequence in ascending order where the smallest ICCID is produced first and is at the end of the tape in the middle of the reel. The user direction of unreeling is according to EIA-481 standard.
![1NCE_eSIM_Reel.png](/img/sim-cards/sim-cards-overview/sim-chips-iot-industrial/63be9d7-1NCE_eSIM_Reel.png)
*** # IoT SIM Chip Industrial eID Identification An eID is a 32-digit global unique identifier number, containing information that identifies the SIM supplier for the physical SIM. Using eUICC feature, the eID is the most important number to identify the SIM. The ICCID may change with the change of the active profile, but eID is unique to the IoT SIM, and it is always the same. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM Card Industrial has the eID of the particular SIM printed on the 4FF physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # IoT SIM Chip Industrial Specifications SIM Cards for mobile network applications follow strict standards for the physical form factor as well as the technology and interfaces. 1NCE IoT SIMs Chip Industrial comply with these technical standard specifications. Besides the key standard compliances, SIM Chips are validated for specific environmental ranges in which they need to be operated in. The table below shows the most important 1NCE IoT SIM Chip Industrial specifications that are relevant for the deployment of the 1NCE IoT SIM Chip Industrial. Furthermore, references to the key standard compliances for the SIM interfaces are referenced.
Parameter 1NCE IoT SIM Chip Industrial
Form Factor (FF) MFF2, QFN8 (IC Package)
Supported Radio Access Technologies (RAT) 2G, 3G, 4G, CAT-M1, NB-IoT
Environmental Temperature -40°C to +105°C
Operating Voltages Class A, B and C (1.62V – 5.5V)
Data Retention Period min. 10 years
Number of profiles max. 10
Read/Write Cycles min. 2.000.000 cycles
Key Standard Compliances 3GPP TR 31.919
ETSI TS 101 220
ETSI TS 102 221
3GPP TS 31.101
3GPP TS 31.111
3GPP TR 31.900
*** # Application Cases IoT SIM Chip Industrial Embedded-SIMs reduce the footprint of the SIM integration and also provide a more rugged and robust connection. In general, the IoT SIM Chip Industrial form factor is more optimized for typical IoT device environments where factors like heavy vibration, higher temperature ranges but also increased security plays a key role. 1NCE recommends the integration of IoT SIMs Chip Industrial in custom developed IoT devices and use cases where extraordinary environmental robustness is needed.\ As the IoT SIMs Chip Industrial is surface mounted to the PCB of a device, it provides higher security against end-user tampering as the SIM Card cannot be easily removed. For prototyping and designing custom IoT devices, special QFN8 adapters are available to adapt an IoT SIM Chip Industrial to the IoT SIM Card Industrial footprint. For any open questions about the detailed 1NCE IoT SIM Chip Industrial product or more extensive help in selecting the right IoT SIM for the specific application case, feel free to contact us (1NCE Contact). --- # eUICC Knowledge Source: https://help.1nce.com/docs/v2/sim-cards/sim-euicc-knowledge/ An eUICC (Embedded Universal Integrated Circuit Card) is a re-programmable SIM card that can be remotely provisioned with different operator connection profiles. This allows users to switch between different carriers without physically changing the SIM card. Unlike a traditional SIM card, which is tied to a specific carrier plan, an eUICC can be reprogrammed over the air (OTA) with new profiles. It simplifies logistics for device manufacturers and network operators, who no longer need to physically swap SIM cards when activating or switching devices between carrier plans. The following sections will cover the basics of 1NCE eUICC. *** # Remote SIM Provisioning (RSP) Remote SIM Provisioning (RSP) in IoT is the process of remotely managing SIM profiles saved on eUICC-capable SIM cards. This includes installation, switching, and deactivation of SIM profiles over-the-air. Before RSP, a change of an operator profile could only be done by physically changing the whole SIM card. With Remote SIM Provisioning, it has become possible to overcome the issues by allowing to add, switch or change a SIM profile remotely over-the-air (OTA). There is no physical difference between eUICC SIM cards and normal non-eUICC SIM cards. The eUICC SIMs are available as solderable MFF2 or put into the SIM slot when used in removable form factors (2FF, 3FF, 4FF). *** # SIM ICCID vs. eID A physical non-eUICC SIM is typically identified using the ICCID, which is printed on the SIM card or chip. When using eUICC, the ICCID can change dependent on the used profiles, thus the ICCID is no longer a static unique identifier. For eUICC SIMs, the eID, a 32-digit global unique identifier number, is used. It is unique and references the physical hardware SIM chip. The eID can be read by the hardware modem using an AT-Command or manufacturer-specific request. For easier physical identification, each 1NCE IoT SIM has the eID of the particular SIM printed on the physical chip card. For more information about eID, please, refer to the official [GSMA documentation](https://www.gsma.com/esim/resources/sgp-29-v1-0-eid-definition-and-assignment-process/) *** # 1NCE RSP Models 1NCE offers three kinds of models, Freedom To Switch, Overtake and Active Model. The differences between these models are explained below. For any open questions about the eUICC models or more extensive help for the specific application case, feel free to contact us (1NCE Contact). ## Freedom To Switch (Insurance) The insurance model is used when the customer requires a new physical eUICC SIM for their device. The 1NCE IoT SIM has the 1NCE profile stored as default. It works out of the box like the IoT SIM Card Business product, but It is possible to change the SIM profile in the future. These are the eUICC capable SIMs : **IoT SIM Card Industrial** and **IoT SIM Chip Industrial**. ## Overtake or Bring your own eUICC (BYOeUICC) If the customer already has an eUICC-capable SIM card from another provider and is using their own RSP platform, it is possible to migrate this eUICC SIM from the customer RSP to 1NCE RSP systems and add the 1NCE profile to the existing eUICC compatible SIM. 1NCE takes over not only the customer connectivity needs but also their eUICC SIMs into the 1NCE RSP platform.
![](/img/sim-cards/sim-euicc-knowledge/001.png)
## Active model 1NCE is looking forward to enabling a RSP ecosystem capable of integrating with other RSP platforms (where SIM profiles are stored). These integrations will allow the customer to actively host and switch between 1NCE and other connectivity profiles using the remote SIM provisioning capabilities. These integrations are standardized by the GSMA specifications. Once the integrations are in place, customers will be able to download profiles and switch between multiple profiles depending on their use case. The active model can be used in the followings scenarios: 1. The customer has an eUICC SIM from another provider and wants to use 1NCE profile for their device.
![](/img/sim-cards/sim-euicc-knowledge/002.png)
2. The customer has an eUICC SIM from 1NCE and wants to use another profile from another provider for their device.
![](/img/sim-cards/sim-euicc-knowledge/003.png)
# Device Requirements for eUICC-capable IoT SIMs The GSMA standards require that the device supports some features to enable the eUICC functionality. The minimum requirement is a device that fulfills the needs to enable the use of eUICC functions. Please note these features are mandatory for the eUICC to execute RSP operations only, for example, downloading profile, enabling a profile, deleting a profile, etc. In case your device does not support this, it will still work normally, which means fulfilling all your connectivity needs, but no profile swapping can happen. You may find more information about eUICC compatibility, providers, and modules [here](https://1nce.com/en-eu/euicc-sim-card-for-iot-esim/euicc-compatible-iot-hardware). --- # 1NCE Technical Support Source: https://help.1nce.com/docs/v2/troubleshooting/troubleshooting-technical-support/ --- # Platform Migration Source: https://help.1nce.com/platform-migration/ # Upgrade to 1NCE Platform 2.0 This section is for **existing 1NCE customers** who are being upgraded to the **New 1NCE Platform 2.0** — 1NCE's new Customer Portal and application layer with Management API and Data Streamer. It documents exactly what changes for each feature, what you need to do, and when. :::warning This is a mandatory platform upgrade All existing customers will be upgraded to the 1NCE Platform 2.0. Some changes require action on your side (for example, OpenVPN reconfiguration or Management API upgrade). Read [Breaking Changes](/platform-migration/breaking-changes/) first to identify what applies to you, and plan enough lead time for each task (see the [Timeline](/platform-migration/timeline/)). ::: ## What 1NCE Platform 2.0 brings We're excited to introduce the **1NCE Platform 2.0**, our upgraded platform built to deliver a faster, more scalable, and future-ready experience for managing your IoT connectivity. With the new platform, you'll benefit from: - **Faster performance** through an improved portal and APIs. - **Greater scalability and resilience** for growing IoT deployments. - **More flexibility and visibility** to better manage your connectivity services. - **Future-ready capabilities**, including onboarding of SGP.32 and upcoming platform innovations. All new features and development happen on the 1NCE Platform 2.0 only. The 1NCE Platform 1.0 receives no new functionality. ## Your Platform The 1NCE Platform 2.0 consists of three layers: - **Customer Portal** - **Application** - **Core network** The 1NCE Platform 2.0 will gradually replace parts of the legacy 1NCE Platform 1.0, which is built on the same components. The Portal and the application layer of the 1NCE Platform 2.0 replace the 1.0 components, while the 1.0 core network with your SIM cards persists and works in parallel to the 1NCE Platform 2.0 core network. ![1NCE Platform 2.0 overview: one account and one Customer Portal, with the 1NCE Platform 1.0 and 2.0 core networks running in parallel](/img/platform-migration/platform-2-0-overview.png) ## What stays the same - **Account IDs** do not change. - **Existing APNs** (including custom APNs and `iot.1nce.net`) keep working — no device reconfiguration is forced. - **Static IP addresses** assigned to your SIMs do not change. ## How this section is organized | Page | What it covers | | --- | --- | | [Hybrid Accounts](/platform-migration/hybrid-accounts/) | The model that lets one account hold 1NCE Platform 1.0 and 1NCE Platform 2.0 SIMs | | [Migration Timeline](/platform-migration/timeline/) | Upgrade phases and cutoff dates | | [Breaking Changes](/platform-migration/breaking-changes/) | The changes that require action, in one place | | [Feature Changes](/platform-migration/feature-changes/internet-breakout/) | Per-feature detail: Internet Breakout, Data Service, VPN, SIM Management, Portal & API, APN | | [Data Streamer Migration](/platform-migration/data-streamer/overview/) | Field-level changes for event and usage data streams | | [Management API Migration](/platform-migration/api-migration/) | Moving from Management API v1 to v2 | | [FAQ](/platform-migration/faq/) | Common questions from the onboarding | :::info Work in progress The 1NCE Platform 2.0 is rolling out in phases and some details may still change. Where a behavior is still being finalized, the relevant page calls it out explicitly. If you have questions about your specific setup, contact [1NCE Technical Support](https://1nce.com/en-eu/support/contact). ::: --- # Management API Migration Source: https://help.1nce.com/platform-migration/api-migration/ # Management API Migration (v1 → v2) If you automate against the **1NCE Management API**, you must migrate from **v1** to **v2** before v1 is retired.
![Deadline December 31, 2026: upgrade to API v2 for all already activated SIM cards](/img/platform-migration/api-v2-deadline.png)
:::warning Management API v1 retires at the end of 2026 The switch to API v2 must be finalized for all customers by the end of 2026. Plan and test your v2 migration well ahead of the cutoff. See the [Migration Timeline](/platform-migration/timeline/). ::: ## What does not change - **Base URL:** the API is served from `https://api.1nce.com/management-api` for both versions. - **Authentication flow:** you still obtain a Bearer token with `POST /oauth/token` (HTTP Basic authentication, `grant_type=client_credentials`), then use the Bearer token on subsequent calls. The authorization spec is version `v2.1.1` for both. - **Rate limits:** unchanged — default **10 TPS**, with customer-specific overrides on request. ## Authentication and credentials The way you **obtain and manage credentials** changes in the portal (the token endpoint itself is unchanged): - Generate credentials under **Account → Management API Access** as OAuth2 **Client-ID + secret** pairs. Create as many as you need. - **Existing API users keep working** — they were moved here automatically. - The **Owner role cannot make API calls** — use a dedicated API credential. See [Portal & API Access](/platform-migration/feature-changes/portal-and-api-access/) for detail. ## Endpoint path change All SIM Management endpoints move from the `/v1/` prefix to `/v2/`. For example, `GET /v1/sims/{iccid}` becomes `GET /v2/sims/{iccid}`. ### Available in v2 The following SIM Management operations are available in the v2 API: | Operation | v1 | v2 | | --- | --- | --- | | List SIMs | `GET /v1/sims` | `GET /v2/sims` | | Get / update a SIM | `GET,PUT /v1/sims/{iccid}` | `GET,PUT /v2/sims/{iccid}` | | SIM status | `GET /v1/sims/{iccid}/status` | `GET /v2/sims/{iccid}/status` | | Reset connectivity | `POST /v1/sims/{iccid}/reset` | `POST /v2/sims/{iccid}/reset` | | Events | `GET /v1/sims/{iccid}/events` | `GET /v2/sims/{iccid}/events` | | Data quota | `GET /v1/sims/{iccid}/quota/data` | `GET /v2/sims/{iccid}/quota/data` | | SMS quota | `GET /v1/sims/{iccid}/quota/sms` | `GET /v2/sims/{iccid}/quota/sms` | | Send / list SMS | `GET,POST /v1/sims/{iccid}/sms` | `GET,POST /v2/sims/{iccid}/sms` | | Get / cancel one SMS | `GET,DELETE /v1/sims/{iccid}/sms/{id}` | `GET,DELETE /v2/sims/{iccid}/sms/{id}` | | Top up a SIM | `POST /v1/sims/{iccid}/topup` | `POST /v2/sims/{iccid}/topup` | ### Not part of the documented v2 set Several v1 operations are **not in the current v2 documentation set**. If you depend on any of these, confirm their availability and replacement with 1NCE before migrating: | Operation | v1 endpoint | | --- | --- | | SIM transfer | `POST /v1/sims/simTransfer` | | Connectivity info | `GET /v1/sims/{iccid}/connectivity_info` | | Usage | `GET /v1/sims/{iccid}/usage` | | Bulk top-up | `POST /v1/sims/topup` | | Auto top-up | `POST /v1/sims/autoTopup` | | Limits | `GET,POST /v1/sims/limits`, `GET /v1/sims/{service}/limits` | | Extension | `POST /v1/sims/extension` | ## Hybrid accounts and legacy SIMs On a [hybrid account](/platform-migration/hybrid-accounts/), the 1NCE Platform 2.0 proxies only a **small subset of Management API endpoints** to the 1NCE Platform 1.0 for legacy SIMs. As a result, some operations available for SIMs native to the 1NCE Platform 2.0 may behave differently — or not be available — for SIMs that are still on the 1NCE Platform 1.0. Test your integration against both legacy and 1NCE Platform 2.0 SIMs during the transition. ## What to do 1. Move your integrations from the `/v1/` endpoints to `/v2/`. 2. Generate (or confirm) credentials under **Account → Management API Access**; stop using the Owner role for API calls. 3. Identify any **v1-only operations** you depend on and confirm their v2 replacement with 1NCE. 4. Test against both **legacy and 1NCE Platform 2.0 SIMs** on a hybrid account. 5. Complete the migration before the **end-of-2026** v1 retirement. ## Try the API Explore and test endpoints in the interactive API Explorer: - [API Explorer (v1)](/api/) — current API reference - [API Explorer (v2)](/api/v2/) — Platform v2 / 1NCE Platform 2.0 API reference --- # Breaking Changes Source: https://help.1nce.com/platform-migration/breaking-changes/ # Breaking Changes This page collects the upgrade changes that may require action on your side. Each row links to the page with the full detail. Review every row that matches your setup, and plan enough lead time for each task (see the [Migration Timeline](/platform-migration/timeline/)). :::tip Little to no action needed for most setups If you do not use OpenVPN, the Management API, the Data Streamer, device-to-device traffic, or throughput above 1 Mbps, the upgrade requires little to no action from you — your account ID, static IPs, and APNs stay the same. ::: ## Changes that may require action | Change | Impact | What to do | Detail | | --- | --- | --- | --- | | **QoS strictly enforced at 1 Mbps** | The default 1 Mbps limit is now a hard limit enforced in the network. | If you rely on higher throughput, move to a higher-speed product tier. | [Data Service](/platform-migration/feature-changes/data-service/) | | **PDP session rounding (1 KB minimum block)** | Usage is rounded up to the nearest kilobyte per PDP session. | Expect a small reported-volume increase; avoid short-running sessions. | [Data Service](/platform-migration/feature-changes/data-service/) | | **Device-to-device communication dropped** | Direct device-to-device (P2P) traffic is **not supported** on the 1NCE Platform 2.0. | Identify any device-to-device flows and re-architect via a backend or breakout. | [Data Service](/platform-migration/feature-changes/data-service/) | | **Default APN changes to `sensor.net`** | SIMs newly ordered on the 1NCE Platform 2.0 default to `sensor.net`. Legacy `iot.1nce.net` and custom APNs are grandfathered. | No device reconfiguration is required for existing SIMs. | [APN](/platform-migration/feature-changes/apn/) | | **OpenVPN becomes per-customer** | Each customer uses certificate-based authentication. | Replace your VPN credential file once. | [VPN Service](/platform-migration/feature-changes/vpn-service/) | | **Management API v1 retiring** | The v1 Management API is retired; you must move to v2. | Migrate integrations to the `/v2/` endpoints (budget 4–8 weeks). | [Management API Migration](/platform-migration/api-migration/) | | **Changed public IP pool** | The breakout public IP pool changes. | If you allowlist breakout IPs, prepare for the different pool. | [Internet Breakout](/platform-migration/feature-changes/internet-breakout/) | | **Shorter TCP idle timeout** | NAT TCP idle timeout drops from 600s to **350s**. | Add keepalives to long-lived TCP sessions. | [Internet Breakout](/platform-migration/feature-changes/internet-breakout/) | | **Data Streamer integrations retiring** | The S3, Datadog, and KeenIO integrations are retired. | Move to Webhook (REST) or AWS Kinesis. | [Data Streamer](/platform-migration/data-streamer/overview/) | | **Data Streamer source IPs change** | The platform source IPs that reach your backend change (SIM IPs do not). | Update your allowlists with the new source IPs. | [Data Streamer](/platform-migration/data-streamer/overview/) | | **Data Streamer event/usage fields change** | Field naming, structure, and availability change; 100% event mapping is not possible. | Validate your integrations against the field-level mapping. | [Data Streamer](/platform-migration/data-streamer/overview/) | | **IMEI Lock configuration changes** | IMEI Lock can be configured globally at the account level in addition to per SIM. | Review your IMEI Lock workflow. | [SIM Management](/platform-migration/feature-changes/sim-management/) | | **Owner role cannot use the API** | The Owner role can no longer make API calls. | Use a dedicated API credential under Account → Management API Access. | [Portal & API Access](/platform-migration/feature-changes/portal-and-api-access/) | | **Third-party access role removed** | The third-party access user role no longer exists (four roles remain). | Move affected users to Admin, User, or Read Only. | [Portal & API Access](/platform-migration/feature-changes/portal-and-api-access/) | --- # Event Data — Platform 1.0 → 2.0 Source: https://help.1nce.com/platform-migration/data-streamer/event-data/ # Event Data: Platform 1.0 → 2.0 An **event record** captures a notable system occurrence related to a SIM or device (device connect/disconnect, PDP context create/delete, quota reached, SIM status changes, location updates). ## Summary of changes The 1NCE Platform 1.0 event stream and Data Streamer 2.0 share the same structure and identical data types for all shared fields. The main differences are: - **Location fields renamed** — flat location fields are split into GTP version-specific fields. - **New operational fields added** — VPN, failure diagnostics, auto-topup, session correlation. - **1NCE Platform 1.0 portal/user fields retired** — user-activity tracking fields are not carried over. ## What stays the same The following fields are identical in name, type, and meaning: | Group | Fields | | --- | --- | | Identifiers | `id`, `timestamp`, `ingestion_timestamp` | | Event classification | `alert`, `description`, `event_severity_id`, `event_source_id`, `event_type_id` | | Device / SIM | `endpoint_*` fields, `sim_id`, `imsi_id` | | Organization | `organisation_id` | | Client info | `detail_client_*` fields | | Network detail | `detail_country_id`, `detail_id`, `detail_mnc`, `detail_tapcode`, most `detail_pdp_context_*` fields | | Volumes | `detail_volume_rx`, `detail_volume_tx`, `detail_volume_total` | ## Fields that are renamed | 1NCE Platform 1.0 field | Data Streamer 2.0 field | | --- | --- | | `detail_session_id` | `detail_pdp_context_ipcan_session_id` | | `detail_pdp_context_ci` | `detail_pdp_context_gtp_v1_uli_ci` | | `detail_pdp_context_lac` | `detail_pdp_context_gtp_v1_uli_lac` | | `detail_pdp_context_rac` | `detail_pdp_context_gtp_v1_uli_rac` | | `detail_pdp_context_sac` | `detail_pdp_context_gtp_v1_uli_sac` | On the 1NCE Platform 1.0, fields like `ci` and `lac` were flat but had different meanings depending on the GTP version. Data Streamer 2.0 separates them to avoid ambiguity. ## Fields that are new ### New operational fields | New field | What it contains | | --- | --- | | `detail_auto_topup_effective` | Whether auto top-up was applied (true/false) | | `detail_data_service_failure_cause` | Reason for a data service failure | | `detail_reason` | General event reason description | | `vpn_id` | VPN connection identifier | | `vpn_provision_status_id` | VPN provisioning status | ### New geolocation fields (GTP v2 — 4G/5G) Entirely new for 4G/5G, providing precise cell identification that was not available before: | New field | What it contains | | --- | --- | | `detail_pdp_context_gtp_v2_uli_cgi_ci` | Cell Identity (CGI) | | `detail_pdp_context_gtp_v2_uli_cgi_lac` | Location Area Code (CGI) | | `detail_pdp_context_gtp_v2_uli_eci` | E-UTRAN Cell Identifier | | `detail_pdp_context_gtp_v2_uli_emenbi` | Extended Macro eNodeB ID | | `detail_pdp_context_gtp_v2_uli_lac` | Location Area Code | | `detail_pdp_context_gtp_v2_uli_menbi` | Macro eNodeB ID | | `detail_pdp_context_gtp_v2_uli_rai_lac` | Location Area Code (RAI) | | `detail_pdp_context_gtp_v2_uli_rai_rac` | Routing Area Code (RAI) | | `detail_pdp_context_gtp_v2_uli_sai_lac` | Location Area Code (SAI) | | `detail_pdp_context_gtp_v2_uli_sai_sac` | Service Area Code (SAI) | | `detail_pdp_context_gtp_v2_uli_tac` | Tracking Area Code | ## Fields that are retired These relate to 1NCE Platform 1.0 portal user activity and are not relevant to network/device events in Data Streamer 2.0: | Retired field | What it contains | | --- | --- | | `user_id`, `user_name`, `user_username` | 1NCE Platform 1.0 portal user identity | | `detail_stale` | 1NCE Platform 1.0 data-freshness indicator | | `detail_support_user_org_id`, `detail_support_username` | 1NCE Platform 1.0 support-access tracking | | `detail_target_username` | Target user of an action (1NCE Platform 1.0 user management) | | `detail_trusted_device_id`, `..._browser`, `..._operating_system`, `..._activation_date` | 1NCE Platform 1.0 MFA / trusted-device feature | | `detail_pdp_context_tariff_profile_id` | Platform 1.0-specific tariff profile concept | ## Practical impact - **Update location queries:** replace `detail_pdp_context_ci/lac/rac/sac` with the GTP version-specific equivalents — `gtp_v1_uli_*` for 2G/3G, `gtp_v2_uli_*` for 4G/5G. - **Session correlation field renamed:** update `detail_session_id` → `detail_pdp_context_ipcan_session_id`. - **Portal/user-activity events are not carried over** (logins, MFA, support access). They are Platform 1.0-specific. - **New diagnostics:** `detail_data_service_failure_cause` and `detail_reason`. - **VPN tracking:** events carry explicit `vpn_id`. - **Richer 4G/5G location:** new `gtp_v2_uli_eci` and `gtp_v2_uli_tac` provide precise cell identification. - **Resolve IDs to names** via the [Reference Data (v2 API)](/platform-migration/data-streamer/reference-data-api/) endpoints; cache responses locally. --- # Data Streamer Migration Overview Source: https://help.1nce.com/platform-migration/data-streamer/overview/ # Data Streamer Migration This set of pages describes the **data field changes** you will experience when upgrading from the **1NCE Platform 1.0 data streams** to **Data Streamer 2.0**. Use it to assess the impact on your integrations before the upgrade. ## Background The 1NCE Platform 1.0 delivers connectivity **event** and **usage** data streams. Data Streamer 2.0 provides the same core connectivity data with platform-specific enhancements, and supports both your existing SIM cards on the 1NCE Platform 1.0 core network and new SIM cards on the 1NCE Platform 2.0 core network. ## What changes for customers | Aspect | Change | | --- | --- | | Data content | Core connectivity data (events, usage, volumes, SIM/device info) remains the same | | Field naming | Some fields are renamed (for example, `session_id` → `ipcan_session_id`) | | Field availability | Some Platform 1.0-specific fields are retired; new fields are added | | Location data | Richer geolocation via GTP v1/v2 User Location Information (ULI) fields | :::warning Not every field maps one-to-one The 1NCE Platform 1.0 event stream is richer than the Data Streamer 2.0 equivalent in some areas. Validate your integrations against the field-level mapping pages below — do not assume a one-to-one mapping. ::: ## Integration and delivery changes Beyond the schema, **how the data reaches you** also changes: - **Retired destinations:** the **AWS S3, Datadog, and KeenIO** integrations are retired and are not available with Data Streamer 2.0. Move affected streams to **Webhook (REST)** or **AWS Kinesis**. Affected customers are informed before their upgrade. - **Source IPs change:** the platform source IPs that deliver stream data to your backend change with the upgrade (your SIM IP addresses do **not** change). If your backend or firewall allowlists the Data Streamer source IPs, update the allowlist — the new IPs are communicated with your technical notification, or contact [1NCE Technical Support](https://1nce.com/en-eu/support/contact). - **SMS Forwarder:** the SMS Forwarder is integrated into Data Streamer 2.0 and works the same way. ## Migration guides | Guide | Contents | | --- | --- | | [Event Data: Platform 1.0 → 2.0](/platform-migration/data-streamer/event-data/) | Field changes for event records | | [Usage Data: Platform 1.0 → 2.0](/platform-migration/data-streamer/usage-data/) | Field changes for usage records | | [Reference Data (v2 API)](/platform-migration/data-streamer/reference-data-api/) | API v2 endpoints for resolving IDs to names | Each guide follows the same structure: **what stays the same**, **what is renamed**, **what is new**, and **what is retired**. ## Key terminology | Term | Meaning | | --- | --- | | Usage record | A record of data consumption (volume transmitted/received) or SMS activity for a SIM during a session | | Event record | A record of a system occurrence (device connected, PDP context created/deleted, quota reached, etc.) | | PDP Context | Packet Data Protocol context — the data connection allowing a device to transmit IP data over the mobile network | | ICCID | Integrated Circuit Card Identifier — unique SIM card number | | IMSI | International Mobile Subscriber Identity — unique subscriber number on the SIM | | IMEI | International Mobile Equipment Identity — unique device hardware identifier | | MNO | Mobile Network Operator | | MCC / MNC | Mobile Country Code / Mobile Network Code — together they identify a specific operator in a country | | RAT | Radio Access Technology (2G, 3G, 4G, 5G, NB-IoT, LTE-M) | | GTP | GPRS Tunnelling Protocol — used for mobile data connections (v1 for 2G/3G, v2 for 4G/5G) | | ULI | User Location Information — geolocation data within GTP signaling | | IP-CAN | IP Connectivity Access Network — the session identifier in Data Streamer 2.0 | --- # Reference Data (v2 API) Source: https://help.1nce.com/platform-migration/data-streamer/reference-data-api/ # Reference Data: 1NCE Platform 2.0 API In the 1NCE Platform 2.0, event and usage data streams contain **only IDs** (not names or descriptions). To resolve these IDs to human-readable information, use the **1NCE Platform 2.0 API**. The 1NCE Platform 2.0 API provides the reference-data endpoints described below. :::info Access via the API only You do not have direct access to internal database tables. All reference-data lookups go through the 1NCE Platform 2.0 API endpoints below. ::: ## Available endpoints ### `GET /countries` Resolves country IDs (`operator_country_id`, `detail_country_id`). | Field | Description | | --- | --- | | `id` | Country identifier | | `country_name` | Full country name (e.g., "Germany") | | `iso_code` | ISO 3166-1 alpha-2 code (e.g., "DE") | | `mcc` | Mobile Country Code (e.g., "262") | | `country_code` | Numeric country code | ### `GET /operators` Resolves operator IDs (`operator_id`, `detail_pdp_context_operator_id`). | Field | Description | | --- | --- | | `id` | Operator identifier | | `operator_name` | Operator name (e.g., "Vodafone D2") | | `country_id` / `country_name` / `country_iso_code` / `country_mcc` | Operator country details | | `mnc` | Mobile Network Code(s) | | `tapcode` | Transfer Account Procedure code(s) | | `ccndc` | Country Code + National Destination Code | ### `GET /organisations` Resolves `organisation_id`. | Field | Description | | --- | --- | | `id` | Organization identifier | | `organisation_name` | Organization/customer name | | `status_id` / `status_description` | Organization status | | `type_id` / `type_description` | Organization type | | `parent_org_id` | Parent organization (hierarchies) | | `preferred_breakout_aws_region` | Preferred AWS breakout region | | `created` | Creation timestamp | ### `GET /sims` Resolves `sim_id`. | Field | Description | | --- | --- | | `id` | SIM identifier | | `iccid` | SIM card number | | `msisdn` | Phone number | | `imsi` / `imsi2` / `imsi3` / `imsi4` | Primary and additional IMSIs (multi-IMSI) | | `eid` | eSIM identity document | | `organisation_id` / `customer_org_id` / `customer_org_name` | Ownership | | `status_id` / `status_description` | SIM status (e.g., "Activated") | | `model_name_external` / `model_manufacturer_name` / `model_form_factor_name` | SIM model details (e.g., "2FF", "3FF", "MFF2") | ### `GET /tariffs` Resolves `tariff_id`, `detail_pdp_context_tariff_id`. | Field | Description | | --- | --- | | `id` | Tariff identifier | | `tariff_name` | Tariff plan name | | `description` | Tariff description | | `organisation_id` | Owning organization | | `apn` | Access Point Name(s) for this tariff | ### `GET /ratezones` Resolves `tariff_ratezone_id`, `detail_pdp_context_ratezone_id`. | Field | Description | | --- | --- | | `id` | Ratezone identifier | | `ratezone_name` | Rate zone name | | `operator_id` / `operator_name` | Associated operator | | `country_id` / `country_name` / `country_iso_code` / `country_mcc` | Country details | | `mncs` / `tapcodes` | MNCs and TAP codes in this ratezone | | `tariff_id` / `organisation_id` | Associations | ### `GET /rat_types` Resolves `rat_type`, `detail_pdp_context_rat_type`. | ID | Technology | Description | | --- | --- | --- | | 1 | 3G | UMTS/WCDMA | | 2 | 2G | GSM/GPRS/EDGE | | 3 | WLAN | Wireless LAN | | 4 | GAN | Generic Access Network | | 5 | HSPA+ | High Speed Packet Access Plus | | 6 | 4G | LTE | | 8 | NB-IoT | Narrowband IoT | | 9 | LTE-M | LTE for Machines (Cat-M1) | | 10 | 5G | NR | ## Fixed mappings (no API call needed) Some IDs have a small, fixed set of values you can hardcode: **Event severity (`event_severity_id`):** 0 = Info, 1 = Warn, 2 = Critical. **Event source (`event_source_id`):** 0 = Network, 1 = Policy Control, 2 = API. **Traffic type (`traffic_type_id`):** 5 = Data, 6 = SMS. **Event type (`event_type_id`):** a fixed set of roughly 70 values. The IDs are unchanged from the 1NCE Platform 1.0; if you need the full mapping table, contact [1NCE Technical Support](https://1nce.com/en-eu/support/contact). ## 1NCE Platform 1.0 vs 2.0 approach | Aspect | 1NCE Platform 1.0 data stream | Data Streamer 2.0 | | --- | --- | --- | | Names in data records | No (IDs only) | No (IDs only) | | How to get names | 1NCE Platform 1.0 API | 1NCE Platform 2.0 API | | SIM / operator / country / tariff details | By ID | 1NCE Platform 2.0 API endpoints | | RAT type name | Not available | `GET /rat_types` | ## Best practices - **Cache reference data locally.** Countries, operators, tariffs, and ratezones change infrequently — refresh daily or weekly rather than per record. - **Use bulk endpoints.** Fetch all operators once and build a local lookup map rather than querying per record. - **Handle missing IDs gracefully.** New operators or ratezones may appear before your cache refreshes — do not fail on unknown IDs. - **Hardcode fixed mappings.** Traffic type, event severity, and event source have small fixed value sets and need no API call. --- # Usage Data — Platform 1.0 → 2.0 Source: https://help.1nce.com/platform-migration/data-streamer/usage-data/ # Usage Data: Platform 1.0 → 2.0 A **usage record** represents a single data-consumption session or SMS activity for a SIM. ## Summary of changes The upgrade from the 1NCE Platform 1.0 usage stream to Data Streamer 2.0 is **minimal**. Both use the same structure and identical data types. The only changes are: - One field is **renamed** (`session_id` → `ipcan_session_id`). - Two fields are **new** (`quota_id`, `rat_type`). - One field is **retired** (`currency_id` — the currency is fixed to EUR for 1NCE). ## What stays the same The following fields are identical in name, type, and meaning: | Group | Fields | | --- | --- | | Identifiers | `id`, `ingestion_timestamp` | | Session window | `start_timestamp`, `end_timestamp` | | Device | `endpoint_id`, `endpoint_imei`, `endpoint_ip_address`, `endpoint_name`, `endpoint_tags` | | SIM | `sim_id`, `imsi_id` | | Operator | `operator_id`, `operator_country_id`, `operator_mnc` | | Organization | `organisation_id` | | Tariff | `tariff_id`, `tariff_ratezone_id` | | Traffic | `traffic_type_id` (5 = Data, 6 = SMS) | | Volumes | `volume_rx`, `volume_tx`, `volume_total` | | Cost | `cost` | ## Fields that are renamed | 1NCE Platform 1.0 field | Data Streamer 2.0 field | What it contains | | --- | --- | --- | | `session_id` | `ipcan_session_id` | Session identifier (UUID) correlating usage with event records | The data content is identical — only the field name changes. "IP-CAN" (IP Connectivity Access Network) is the standard telecom term for this session concept. ## Fields that are new | New field | What it contains | | --- | --- | | `quota_id` | Quota plan identifier active at time of consumption | | `rat_type` | Radio Access Technology ID (resolve via `GET /rat_types`) | ### RAT type values | ID | Technology | | --- | --- | | 1 | 3G | | 2 | 2G | | 3 | WLAN | | 4 | GAN | | 5 | HSPA+ | | 6 | 4G | | 8 | NB-IoT | | 9 | LTE-M | | 10 | 5G | ## Fields that are retired | Retired field | What it contains | Notes | | --- | --- | --- | | `currency_id` | Currency identifier | Not exposed in Data Streamer 2.0 — the currency is fixed to EUR for 1NCE | ## Practical impact - **Field rename:** update any code or query referencing `session_id` to use `ipcan_session_id`. The format and content are identical. - **New capabilities:** `rat_type` enables filtering and reporting by network technology; `quota_id` links usage to specific quota allocations. - **Currency:** if you read `currency_id`, remove the dependency — all 1NCE costs are in EUR. - Resolve IDs to names via the [Reference Data (v2 API)](/platform-migration/data-streamer/reference-data-api/) endpoints. --- # FAQ Source: https://help.1nce.com/platform-migration/faq/ # Frequently Asked Questions Common questions from the 1NCE Platform 1.0 → 1NCE Platform 2.0 onboarding. For detail, follow the links to the relevant feature pages. ## Network & Connectivity **Will my static IP addresses stay the same?** Yes. Static IP addresses assigned to your SIMs do not change. **Will the public breakout IPs change?** Yes. The public breakout IPs change on the 1NCE Platform 2.0 — review the exact IP ranges in the v2 documentation. If you allowlist breakout IPs, update your allowlist. See [Internet Breakout](/platform-migration/feature-changes/internet-breakout/). **Is IP blacklisting available as a self-service feature?** No. IP blacklisting is not planned as a self-service feature on the 1NCE Platform 2.0. **Will the APN change for existing SIM cards?** No. Existing APNs — including custom APNs and `iot.1nce.net` — remain valid. You can keep your current APN and optionally add a new one; no reconfiguration is required. See [APN](/platform-migration/feature-changes/apn/). **Can I keep using `iot.1nce.net` as my APN?** Yes. `iot.1nce.net` continues to work on the 1NCE Platform 2.0 and you are not forced to change. If you are already planning a firmware rollout, it is a convenient opportunity to also move to the new APN. ## IMEI Lock **Can I set different IMEI Lock settings per SIM card?** Yes. On the 1NCE Platform 2.0, IMEI Lock can be configured **globally at the account level and per individual SIM**. See [SIM Management](/platform-migration/feature-changes/sim-management/). ## VPN & Migration Procedure **What does the migration procedure look like for VPN customers?** You replace your VPN credential file once. The transition is seamless in the background — both the 1NCE Platform 1.0 and the 1NCE Platform 2.0 can be served in parallel via OpenVPN during the migration window, so there is no forced cutover. Support is available. See [VPN Service](/platform-migration/feature-changes/vpn-service/). **What about VPN connectivity during the transition?** You connect to the VPN endpoint, and via OpenVPN both the 1NCE Platform 1.0 and the 1NCE Platform 2.0 are served — so you are covered on both sides during the transition period. Do not run both the 1NCE Platform 2.0 and 1NCE Platform 1.0 VPN connections simultaneously. ## Data Streamer & SMS **Is the SMS Forwarder still available?** Yes. The SMS Forwarder has been integrated into the Data Streamer and works the same way, with support for all migration types. Note that AWS S3 and similar legacy destinations are being retired — affected customers are informed before migration. See [Data Streamer Migration](/platform-migration/data-streamer/overview/). **Will my account ID change?** No. Account IDs remain unchanged. **Will the session token expiry timer in the portal change?** No. The token expiry behavior remains the same. **When will reporting be available on the 1NCE Platform 2.0?** Reporting will be available once the underlying platform integration is complete, expected around July 2026. ## API & Permissions **Can I set different permissions per API key?** Not currently. Granular per-key permissions are not supported at launch but are planned for the future. See [Portal & API Access](/platform-migration/feature-changes/portal-and-api-access/). **Can the account Owner role still use the API?** No. The Owner can authenticate and retrieve an API key, but the Owner role is not authorized as an API user — the key cannot be used to make API calls. Use a dedicated API credential under Account → Management API Access. **Will API rate limits change?** No. Rate limits follow the same logic as before and defaults remain unchanged. Custom per-customer overrides are still available on request. ## Still have questions? Contact [1NCE Technical Support](https://1nce.com/en-eu/support/contact), or review the [Breaking Changes](/platform-migration/breaking-changes/) summary to find what applies to your setup. --- # APN Source: https://help.1nce.com/platform-migration/feature-changes/apn/ # APN This page explains what happens to your APN configuration on the 1NCE Platform 2.0. ## Default APN | | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | Default APN | `iot.1nce.net` | `sensor.net` | 1NCE Platform 2.0 SIMs default to `sensor.net`. ## Existing and custom APNs are grandfathered Existing customers retain their current APNs indefinitely, including custom APNs and `iot.1nce.net`. You can keep your current APN and optionally add a new one — no device reconfiguration is forced. If you are already planning a firmware rollout or device update, that is a convenient opportunity to also move to the new APN — but it is optional. ## What to do - **Existing SIMs:** nothing. Your APN keeps working. - **New SIMs:** expect `sensor.net` as the default APN. - **Optional:** migrate to the new APN opportunistically during a planned device or firmware update. --- # Data Service Source: https://help.1nce.com/platform-migration/feature-changes/data-service/ # Data Service This page covers the data-plane behavior changes on the 1NCE Platform 2.0: throughput enforcement, usage rounding, device-to-device traffic, multiple PDP sessions, and session timeouts. ## QoS / throughput enforcement | | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | Default limit | 1 Mbps | 1 Mbps | | Enforcement | Only where roaming partners enforced it — customers could exceed the limit on non-enforcing networks | Strictly enforced for all networks | On the 1NCE Platform 2.0, QoS limits are enforced per PDP context. The default is 1 Mbps, with custom speeds available. Packets exceeding the limit are dropped by the network, which can lead to retransmission attempts and transmission issues. Be aware of these limits when designing your application, especially for latency-sensitive or bulk-transfer workloads. If you need higher speeds, contact support. ## Session rounding | | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | Rounding | no rounding | Per PDP session, at session end (nearest KB) | In v2 usage is rounded per PDP session at the end to the nearest kilobyte. | Metric | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | 100 bytes in 1 PDP session | 0.1 KB | 1 KB (rounded up) | | 100 × 1-byte PDP sessions | 0.1 KB | 100 KB (1 KB per session) | | 1 PDP session with 100 × 1-byte sends | 0.1 KB | 1 KB (rounded up) | **Recommendation:** Use long-running PDP sessions to minimize rounding impact. A single PDP session with multiple sends accrues less quota than many short sessions, since rounding applies only at session end. ## Device-to-device (P2P) connectivity Direct device-to-device (peer-to-peer) communication worked on the 1NCE Platform 1.0 and is not supported on the 1NCE Platform 2.0. If you have devices that talk directly to each other over the cellular network, identify those flows and re-architect them to route through a backend service or internet breakout. ## Multiple PDP sessions Multiple PDP sessions are supported on the 1NCE Platform 2.0. However, for IoT devices, it is recommended to use only one active PDP session to avoid compatibility issues. ## PDP context and GTP timeouts GTP timeouts differ on the 1NCE Platform 2.0: - **GTP-C:** there is no timeout on the 1NCE Platform 2.0, unlike the legacy 50-day reset behavior. - **GTP-U:** a 7-day timeout closes the PDP session. This timeout is reset by any single data byte sent or received. ## What to do - If you need throughput higher than 1 Mbps, contact support for custom speed options. - Use long-running PDP sessions to minimize quota consumption from rounding. - Identify and re-architect any device-to-device traffic to use backend services or internet breakout. - For IoT devices, use only one active PDP session. --- # Internet Breakout Source: https://help.1nce.com/platform-migration/feature-changes/internet-breakout/ # Internet Breakout This page describes how internet breakout behaves on the 1NCE Platform 2.0 compared with the 1NCE Platform 1.0. ## Routing mode On the **1NCE Platform 2.0 core network**, your organization is locked to the breakout region of the 1NCE entity you are contracted with. For example, a customer of 1NCE Inc. uses the US breakout. This applies to **new SIM cards** provisioned on the 1NCE Platform 2.0 core network. **Existing SIM cards keep their current breakout behavior unchanged** — including automatic mode. They remain on the 1NCE Platform 1.0 core network. Available breakout regions in v2: - Frankfurt - US - APAC If you currently use manual mode in v1, your configuration will be migrated to v2. Customers can contact support to change the breakout region configuration. :::note Automatic mode on the 1NCE Platform 2.0 An automatic routing mode for the 1NCE Platform 2.0 core network is planned for a future release. Until then, new SIM cards use your entity's breakout region. ::: ## Public IP ranges Public breakout IPs will change on the 1NCE Platform 2.0. Review the exact IP ranges in the v2 documentation. ## NAT gateway The 1NCE Platform 2.0 uses AWS-managed NAT gateways. Connections may be disconnected sooner during idle periods. See session timeouts below. | Protocol | 1NCE Platform 1.0 | 1NCE Platform 2.0 | Change | | --- | --- | --- | --- | | **TCP idle timeout** | 600s | 350s | Reduced | | **UDP idle timeout** | 120s | 120s | No change | When the TCP idle timeout is exceeded, the AWS NAT gateway sends a TCP RST and the connection is dropped. For UDP, an ICMP "destination unreachable" is returned after the idle window. ## What to do - Existing SIM cards: no action — their breakout behavior does not change. - New SIM cards: the breakout region of your 1NCE entity applies; contact support if you need a different region. - Review the public breakout IPs in v2 documentation. - If you run long-lived TCP sessions, add TCP keepalives to avoid disconnection at the 350-second idle timeout. - Check NAT gateway timeout behavior for your application needs. --- # Portal & API Access Source: https://help.1nce.com/platform-migration/feature-changes/portal-and-api-access/ # Portal & API Access This page covers how you authenticate and manage users on the 1NCE Platform 2.0. For the endpoint-level API changes, see [Management API Migration](/platform-migration/api-migration/). ## Portal With the 1NCE Platform 2.0, we have improved and simplified the user experience across several areas. You can find full details about the Customer Portal updates [here](/docs/v2/1nce-portal/portal-dashboard/). ## API credentials | | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | Where credentials live | Created as an **"API User"** in your user list | **Account → Management API Access** | | Credential type | API user (username-based) | **OAuth2 Client-ID + secret** | | How many | One user | **Self-generate as many as you need** | On the 1NCE Platform 2.0, you generate your own API credentials under **Account → Management API Access**. Each credential is an OAuth2 **Client-ID and secret** pair. You no longer provide unnecessary user information (such as a phone number or name) just to create API access. :::tip Existing API users keep working If you already have a user of type **API**, no action is required — it has been **moved automatically** to Account → Management API Access and keeps working with the v2 Management API. ::: ## The Owner role cannot use the API The account **Owner** can authenticate and retrieve an API key, but the **Owner role is not authorized as an API user** — the key cannot actually be used to make API calls. :::warning Use a dedicated API credential Do not build integrations against the Owner role. Generate a dedicated credential under **Account → Management API Access** and use that for API calls. ::: ## User roles The third-party access role is **removed**. The 1NCE Platform 2.0 has **four** roles: | Role | Use | | --- | --- | | **Owner** | Account owner (cannot use the API) | | **Admin** | Full hands-on access | | **User** | Hands-on access | | **Read Only** | View-only access | If you used the **third-party access role**, move those users to the role that best fits — **User** for hands-on access or **Read Only** for view-only. ## API permissions and rate limits - **Per-key permissions:** granular permissions per API key (RBAC) are **not available at launch**. They are planned for the future. - **Rate limits:** unchanged. The default is **10 TPS**, with customer-specific overrides available on request (for example, 100 TPS). ## What to do - Generate API credentials under **Account → Management API Access** (or rely on your auto-migrated API user). - Repoint any integration that used the **Owner** role to a dedicated API credential. - Migrate any **third-party access** users to Admin, User, or Read Only. - Review [Management API Migration](/platform-migration/api-migration/) for the v1 → v2 endpoint changes. - Explore the endpoints in the [API Explorer (v2)](/api/v2/). --- # SIM Management Source: https://help.1nce.com/platform-migration/feature-changes/sim-management/ # SIM Management This page covers the SIM-level configuration changes on the 1NCE Platform 2.0. ## IMEI Lock IMEI Lock is available on both the 1NCE Platform 1.0 and 1NCE Platform 2.0. On the 1NCE Platform 2.0, IMEI Lock can be configured globally at the account level and per individual SIM. ## SIM IP Address Static IP addresses assigned to your SIMs do not change and will carry over to the 1NCE Platform 2.0. New IP spaces will be allocated with /16 CIDR blocks, different from the /24 or /22 blocks used previously. For a list of available IP spaces on the 1NCE Platform 2.0, see the v2 documentation. If you need custom IP spaces, please contact support. --- # VPN Service Source: https://help.1nce.com/platform-migration/feature-changes/vpn-service/ # VPN Service This page covers how OpenVPN changes on the 1NCE Platform 2.0 and what you need to do to migrate. ## Authentication | | 1NCE Platform 1.0 | 1NCE Platform 2.0 | | --- | --- | --- | | Authentication | Username / password | **Certificate-based** | | Configuration | Separate credentials + configuration files | One configuration file | On the 1NCE Platform 2.0, OpenVPN uses **certificate-based authentication** instead of username and password. You receive a single configuration file that replaces your two (credentials + configuration) existing ones. :::info Certificate renewal On the 1NCE Platform 2.0, authentication certificates are valid for **two years**. Plan for certificate renewal every two years as part of your operations. ::: :::note One connection per customer By default, you can run **one OpenVPN connection per customer account**. If you need multiple connections, contact 1NCE Support to file a service ticket. ::: ## Hybrid mode — simpler migration During migration, use **hybrid mode** to connect to both core networks through a single OpenVPN connection. This is the simplest approach: 1. Download the 1NCE Platform 2.0 configuration file from the Portal. 2. Replace your current configuration file with the new one. 3. Restart your VPN client. From that point forward, a **single OpenVPN connection serves both your 1NCE Platform 2.0 and 1NCE Platform 1.0 core network traffic**. The backend automatically routes your migrated and not-yet-migrated SIMs — you manage only one client throughout the transition. :::danger Do not run both VPNs simultaneously Do **not** run both the 1NCE Platform 2.0 and 1NCE Platform 1.0 VPN connections at the same time. Running both connections simultaneously will not work. Complete the configuration swap as a single cutover step. ::: :::info Fallback to old configuration If you need to roll back during migration, switch back to your old configuration file, restart the VPN client, and contact 1NCE Support for help if needed. ::: ## What to do - Download the 1NCE Platform 2.0 configuration file during your migration window. - Swap your configuration file and restart the VPN client. - Plan for certificate renewal **every two years**. - If you need **multiple connections**, contact 1NCE Support. - After migration, your VPN should work exactly as before — traffic flows through a single OpenVPN connection that serves both core networks. --- # Hybrid Accounts Source: https://help.1nce.com/platform-migration/hybrid-accounts/ # Hybrid Accounts ## Hybrid accounts in your 1NCE Customer Portal A **Hybrid Account** allows you to manage both your existing SIM cards on the **1NCE Platform 1.0 core network** and any new SIM cards shipped after **October 1, 2026**, on the **1NCE Platform 2.0 core network** within a single account. All SIM cards — existing and new — can be managed in one place through the 1NCE Platform 2.0 Portal and application layer. Therefore, your legacy 1NCE Platform 1.0 Portal will no longer be accessible, as all functionality is provided through the 1NCE Platform 2.0 Portal. ## Integration updates As part of the transition to the 1NCE Platform 2.0, there are three main integration points that require your attention: **API**, **Data Streamer**, and **VPN**. While your existing integrations will mainly continue to support your current SIM cards, an upgrade is required to fully support SIM cards on the 1NCE Platform 2.0. ### API API users will be migrated to the 1NCE Platform 2.0 Portal application. With **API v2**, you can access and manage both your existing SIM cards on the 1NCE Platform 1.0 core network and new SIM cards on the 1NCE Platform 2.0 core network. Your most important current v1 API calls will continue to work for existing SIM cards until the end of the year. To avoid any disruption, we recommend upgrading to API v2 as soon as possible. See [Management API Migration](/platform-migration/api-migration/). ### Data Streamer Your current Data Streamer will continue to provide events and data for your existing SIM cards. However, to receive events and data for SIM cards ordered after October 1, 2026, you will need to upgrade to **Data Streamer 2.0**. This version supports both existing SIM cards on the 1NCE Platform 1.0 core network and new SIM cards on the 1NCE Platform 2.0 core network. See [Data Streamer Migration](/platform-migration/data-streamer/overview/). ### VPN Your current VPN will continue to support your existing SIM cards. However, to send and receive data for SIM cards ordered after October 1, 2026, you will need to upgrade to **VPN 2.0**. The new VPN endpoint supports both existing SIM cards on the 1NCE Platform 1.0 core network and new SIM cards on the 1NCE Platform 2.0 core network. To avoid any disruption, we recommend upgrading to VPN 2.0 as soon as possible. See [VPN Service](/platform-migration/feature-changes/vpn-service/). ## Rollout schedule | Tenant | Hybrid accounts available | | --- | --- | | 1NCE Inc. | **August 2026** | | Other tenants | **Late October 2026** | From **October 1, 2026**, the 1NCE Platform 2.0 is the default for new orders on 1NCE Inc. accounts; all other tenants follow starting **Q4 2026**. See the [Migration Timeline](/platform-migration/timeline/) for the full schedule. ## What you can rely on during the transition - Your **account ID** does not change. - Your **static SIM IP addresses** do not change. - Your **existing APNs** keep working (see [APN](/platform-migration/feature-changes/apn/)). - Your **existing Management API users** are moved automatically and keep working. - During the VPN upgrade, both 1NCE Platform 1.0 and 1NCE Platform 2.0 traffic can be served in parallel so there is **no forced cutover** (see [VPN Service](/platform-migration/feature-changes/vpn-service/)). ## What still requires action Even with hybrid accounts, some changes need preparation. Review [Breaking Changes](/platform-migration/breaking-changes/) and the per-feature pages to find what applies to your setup, and plan enough lead time for each task. --- # Migration Timeline Source: https://help.1nce.com/platform-migration/timeline/ # Migration Timeline The upgrade to the 1NCE Platform 2.0 is a **mandatory platform upgrade** and runs in phases through the end of 2026. Use this page to understand when each milestone happens. ![Your upgrade journey in three steps: prepare your setup now (VPN, Data Streamer, API v2), receive your upgrade confirmation by email in August 2026, and complete your setup before your first shipment after October 1, 2026](/img/platform-migration/upgrade-journey.png) ## Upgrade phases | When | Milestone | | --- | --- | | **August 2026** | **1NCE Inc. accounts:** continuous upgrades to the 1NCE Platform 2.0 begin. You will be informed via email once your account has been upgraded. | | **October 1, 2026** | **1NCE Inc. accounts:** new SIM card orders ship on the 1NCE Platform 2.0 core network. Existing SIM cards are not affected. | | **Q4 2026** | **All other tenants:** continuous upgrades begin, and new SIM card orders ship on the 1NCE Platform 2.0 core network. You will be informed via email once your account has been upgraded. | | **End of 2026** | **All customers:** **Management API v1 retired** — the switch to API v2 must be finalized. Hard cutoff for new activations on the 1NCE Platform 1.0. | :::note Tenant-specific timelines The August schedule applies to 1NCE Inc. accounts. 1NCE GmbH and APAC tenants follow in Q4 2026 — you will be informed via email ahead of your upgrade. ::: ## Cutoff dates to plan around
![Deadline December 31, 2026: upgrade to API v2 for all already activated SIM cards](/img/platform-migration/api-v2-deadline.png)
:::warning Management API v1 retires at the end of 2026 If you use the Management API, plan your upgrade to API v2 well before the cutoff. See [Management API Migration](/platform-migration/api-migration/). ::: :::warning 1NCE Platform 1.0 new-activation cutoff From the end of 2026, new activations on the 1NCE Platform 1.0 are no longer possible. New orders ship on the 1NCE Platform 2.0 core network from **October 1, 2026** for 1NCE Inc. accounts, and starting **Q4 2026** for all other tenants. :::