Integrating an EIM solution

This section describes the steps involved in the integration of eSIM IoT Remote Manager with IMPACT. This is used for eSIM profile download to devices that are constrained.

  1. Registering an eIM server as an application

    In order to receive notifications and responses from the device, the eIM callback URL must be registered with IMPACT IoT.

    For more information on application callback registration, see Registration section in this document.

  2. Subscribing to an IPA message resource

    The Agent in the Device that is handling the eSIM is call the IoT Profile Assistant (IPA).

    For the application callback to receive the uplink IPA messages from device, a resource subscription on 3443/0/3 is required by the eIM. This is so that messages from the IPA can be received and sent to the EIM.

    Table 1. Subscribing to an uplink message from the device
    Title Subscribing to an uplink message from the device
    URL http://impact_url/m2m/subscriptions?type=resources
    Method POST
    Content-Type application/json
    Sample Call 
    curl -X POST \
  'http://impact_url/m2m/subscriptions?type=resources' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ZXNpbTplc2lt' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 7e641e14-625b-42a8-aec4-eeaa168bc6c3' \
  -H 'cache-control: no-cache' \
  -d '{
    "resources": [
        {
            "resourcePath": "3443/0/3"
        }
    ],
    "subscriptionType": "resources",
    "deletionPolicy": 0
}'
    Response body
    {
    "subscriptionId": "6c7f8dda-9672-457c-b9e3-3eb6fd1e06f5",
    "msg": "Success",
    "code": 1000
}
    Success Code 
    Response Code: 202
    Error Code 
    400 : Bad Request
    401 : Unauthorized 
    403 : Forbidden 
    404 : Not Found
  3. Extracting a deviceID/serialnumber of the device using the EID

    The EIM uses the concept of eUICC identifier (EID) to identify the device to be managed. IMPACT uses the Device id which is an internal identifier and FullDeviceiD which is usually the serial number of the device.

    Use the following sample request IMPACT API to get the device details with EID. In the response the the protocolType and protocolRealm values may vary and are not significant.

    Table 2. Extracting a deviceID/serialnumber of the device using the EID
    Title Extracting a deviceID/serialnumber of the device
    URL http://impact_url/rest/device/89001012012341234567890123456789?idField=eid
    Method GET
    Content-Type application/json
    Sample Call

    Sample call:

    curl -X GET \
  'http://impact_url/rest/device/89001012012341234567890123456789?idField=eid' \
  -H 'Authorization: Basic ZXNpbTplc2lt' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 40930470-5935-46d3-aece-b5ec5ab5cbfc' \
  -H 'cache-control: no-cache'

    Response body :

    {
  "id": 4004,
  "updatedOn": 1723009037397,
  "createdOn": 1722924105114,
  "deviceId": "988810017032099",
  "fullDeviceId": "urn:imei:988810017032099",
  "provisioningSource": "Auto created (ZT)",
  "tenantId": 22,
  "eid": "89001012012341234567890123456789",
  "managed": true,
  "inUse": true,
  "model": "Sensor",
  "manufacturer": "Generic",
  "os": "other",
  "protocolType": "LWM2M",
  "logging": false,
  "firmwareVersion": "2.2",
  "hssSubscribe": false,
  "protocolRealm": [
    "LWM2M"
  ],
    "lastSeen": "2024-08-07T05:37:17.396Z",
    "announcedMake": "Nokia",
    "announcedModel": "Lightweight M2M Client",
    "operationalState": [],
    "pushChannels": []
  },
  "customAttributes": {},
  "serviceTags": [],
  "dynamicVariables": [],
  "userTags": [],
  "deviceProtocolData": {
    "data": [
      "{\"path\": \"/1\"}",
      "{\"path\": \"/2\"}",
      "{\"path\": \"/3\"}",
      "{\"path\": \"/4\"}",
      "{\"path\": \"/5\"}",
      "{\"path\": \"/6\"}",
      "{\"path\": \"/7\"}",
      "{\"path\": \"/8\"}",
      "{\"path\": \"/9\"}",
      "{\"path\": \"/20\"}",
      "{\"path\": \"/10\"}",
      "{\"path\": \"/11\"}",
      "{\"path\": \"/4/0\"}",
      "{\"path\": \"/12\"}",
      "{\"path\": \"/5/0\"}",
      "{\"path\": \"/13\"}",
      "{\"path\": \"/14\"}",
      "{\"path\": \"/3/0\"}",
      "{\"path\": \"/15\"}",
      "{\"path\": \"/16\"}",
      "{\"path\": \"/1/0\"}",
      "{\"path\": \"/19\"}",
      "{\"path\": \"/16/0\"}",
      "{\"path\": \"/16/1\"}"
    ]
  },
  "pcapEnabled": false
}
    Success Code 
    Response Code: 200
    Error Code 
    400 : Bad Request
    401 : Unauthorized 
    403 : Forbidden 
    404 : Not Found
    Note: The fullDeviceId field in the device details correspond to the serial number of the device.

  4. Sending a message to a IPA

    When sending a message to the IPA in the device us the FullDeviceID to direct the payload to the Device. Direct the downlink operation towards the device on object-resource 3443/0/2.
    Table 3. Sending the downlink message to the device
    Title Sending the downlink message towards the device
    URL http://impact_url/m2m/endpoints/urn:imei:988810017032099/3443/0/2?needNotification=true
    Method PUT
    Content-Type multipart/form-data
    Sample Call

    Sample call :

    curl -X PUT \
  'http://impact_url/m2m/endpoints/urn:imei:988810017032099/3443/0/2?needNotification=true' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic ZXNpbTplc2lt' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 6eebc3e1-be93-4d9d-a02d-964c945f86e4' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary= – WebKitFormBoundary7MA4YWxkTrZu0gW' \
  
   ------WebKitFormBoundary7MA4YWxkTrZu0gW    
   Content-Disposition: form-data;
   name="resourceValue"; filename="/C:/Users/rungaral/Downloads/1MB.bin"
   Content-Type: application/octet-stream

   (data)
   ------WebKitFormBoundary7MA4YWxkTrZu0gW--

    Response body

    {
    "requestId": "88995b24-bc5d-433e-8420-788aa186b5f6",
    "msg": "Accepted",
    "code": 1002
}
    Success Code 
    Response Code: 202
    Error Code 
    400 : Bad Request
    401 : Unauthorized 
    403 : Forbidden 
    404 : Not Found

    Callback response to the Write operation:

    Sample notification with the EID included in the response:

    POST /url/to/app/callback HTTP/1.1
Content-Type: application/json

{"reports":[],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[{"serialNumber":"urn:imei:988810017032099",
"timestamp":1722328026917,"requestId":"88995b24-bc5d-433e-8420-788aa186b5f6","eId":"89001012012341234567890123456789","resources":
[{"resourcePath":"3443/0/2","value":null}],"result":{"code":0,"subCode":null,"reason":"Success"},"operationType":"write"}]}
  5. Notification of IPA message from device to the application callback:

    This message procedure is the result of a subscription and is triggered when a device sends a message from the IPA to the EIM.

    Sample notification of a message from the IPA destined to the EIM. The message is encoded in Base 64. The EID is included in the messages. The protocolType values may vary and are not significant.

    Sample notification:

    POST /url/to/app/callback HTTP/1.1
Content-Type: application/json
{"reports":[{"serialNumber":"urn:imei:988810017032099","timestamp":1722327381760,
"subscriptionId":"6c7f8dda-9672-457c-b9e3-3eb6fd1e06f5","resourcePath":"3443/0/3",
"value":"qCwWG5mb6wtQLElC7lhKNicYCooXWm2GMzTI3s5Cwk4iNo9qsIDR4aC7LeZijtRfy8imReYfE1wgY5t5vYpRC2pqdGvG4Aa5b8Cxt/mS1ipvcXrobplribcyvkVYIOgcywEwt9Al0ewARnUSq1qYanpf1sG0iA165Vkrc/fKW+RkVrgoA5n0rot/ZG1UFKRqZctX2EG/hujPwq+OGNfybarKuqZbhw8lvlJRYzUilTg+p0pgogr1aUk9glzfFlpc5P/MqBd2hZM5skOwcaKdHia9J7XoMCAWYAEvipFyKo+uXB5UOmfsERHIilWRhwSZ0x1IwCn9JlXRAYFAGAlg8XbjY2EMLi4RTfDYjQFBHlcP3ycg/VsRLI8OU0mC4GRGAln4upjTzw9sg/RZkPOBpjcq0rQBiNl5QcdyUIImkT7pumrnKwsRNd5wxzX0QX39vZpQb1hGvnbBXf/B7gBDlhUG9eHbttUvhqnX9ESlCDim7DdjJTPwb54o7us/7u+ER02V9/57i6I/WnLcfFW+gAz7qyISHuwpmwWfUxS20UuTH8Ocrmd9mVP2E9H9wZXNnQ51Xsx2FIwujKqjr+kQRt8++/RMo0cFBRLX0wqaZU4afACdhMlbOAIQVDF29I52aaab8vo4XfcJDfQbS2VuKdmSZpw=",
"customAttributes":{},"protocol":"LWM2M","eId":"89001012012341234567890123456789"}],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[]}
    Note: The field reports[0] value contains the IPA message encoded in Base64 format.