Missing Documentation on how to provision devices

[jason-fox]

IoT Agent Node Lib version the issue has been seen with

3.2.0

Bound or port used (API interaction)

Northbound (Provision API and NGSI Interactions)

NGSI version

NGSIv2

Are you running a container?

Yes, I am using a contaner (Docker, Kubernetes...)

Image type

normal

Expected behaviour you didn't see

Related #1396 - No documentation about the correct provisioning of Devices can be found, and techniques which used to work prior to 3.4.0 no longer work due to the removal of the duplication of attributes measures.

Without documentation, users will not know how to upgrade.

Unexpected behaviour you saw

I used to provision my Groups to hold common static data like this:

 {
     "apikey":      "3314136",
     "cbroker":     "http://orion:1026",
     "entity_type": "Lamp",
     "resource":    "/iot/d",
     "protocol":    "PDI-IoTA-UltraLight",
     "transport":   "HTTP",
     "timezone":    "Europe/Berlin",
     "commands": [ 
        {"name": "on","type": "command"},
        {"name": "off","type": "command"}
     ],
     "attributes": [
        {"object_id": "s", "name": "state", "type":"Text"},
        {"object_id": "l", "name": "luminosity", "type":"Integer",
          "metadata": {"unitCode": {"type": "Text","value": "CDL"}}
        }
     ],
     "static_attributes": [
          {"name": "category", "type":"Text", "value": ["actuator","sensor"]},
          {"name": "controlledProperty", "type": "Text", "value": "light"},
          {"name": "function", "type": "Text", "value":["onOff", "sensing"]},
          {"name": "supportedProtocol", "type": "Text", "value": ["ul20"]},
          {"name": "supportedUnits", "type": "Text", "value": "CDL"}
     ]
   },

Meaning a device could be created like this:

 {
      "device_id": "lamp001",
      "entity_name": "Lamp:001",
      "entity_type": "Lamp",
      "endpoint": "http://iot-sensors:1041/iot/lamp001",
      "static_attributes": [
        {"name": "refStore", "type": "Relationship","value": "urn:ngsi-ld:Store:001"},
        {"name":"location", "type":"geo:json", "value": {
            "coordinates": [13.3986,52.5547],
            "type": "Point"
          }
        }
      ]
    }

Meaning that a combination of all my static data and commands would be registered in the context broker.

HOWEVER, with 3.4.0 this is no longer the case - none of the static data is passed into the context broker. This is a deliberate change (obviously 😄 ) - but it is documented nowhere, and it is not obvious how to fix it so the static data can be injected properly.

My guess is that people will try to use the NGSI-v2 tutorials as a prototype for provisioning, so I'd like to know what will work in the future.

It looks to me like the removal of plugin/createInitialEntity etc should really be identified as a major version change rather than minor version - basically 3.4.0 is really 4.0.0-alpha (since I see more changes are to come) - it is unexpected that devices that used to provision correctly no longer do so.

Steps to reproduce the problem

No response

Configs

environment:
    - "IOTA_CB_HOST=orion"
    - "IOTA_CB_PORT=1026"
    - "IOTA_NORTH_PORT=4041"
    - "IOTA_REGISTRY_TYPE=mongodb"
    - "IOTA_MONGO_HOST=mongodb"
    - "IOTA_MONGO_PORT=27017"
    - "IOTA_MONGO_DB=iotagent-json"
    - "IOTA_HTTP_PORT=7896"
    - "IOTA_PROVIDER_URL=http://iot-agent:4041"

Log output

No response

[AlvaroVega]

I reckon that 3.4.0 is like a 4.0.0

[jason-fox]

@AlvaroVega - There is still currently one difference between LD and v2 provisioning - provisioning static attributes in the group. does not duplicate onto the LD context broker when an update occurs. I was wondering if createInitialEntityFake has anything to do with this?

e.g.

{
     "apikey":      "3020035",
     "cbroker":     "http://orion:1026",
     "entity_type": "Bell",
     "resource":    "/iot/d",
     "protocol":    "PDI-IoTA-UltraLight",
     "transport":   "HTTP",
     "timezone":    "Europe/Berlin",
     "commands": [ 
        {
          "name": "ring",
          "type": "command"
        }
      ],
      "static_attributes": [
          {"name": "category", "type":"Text", "value": ["actuator"]},
          {"name": "controlledProperty", "type": "Text", "value": "noiseLevel"},
          {"name": "function", "type": "Text", "value":["onOff"]},
          {"name": "supportedProtocol", "type": "Text", "value": ["ul20"]}
      ]
   },

And I get the following Entity:

{
    "id": "Bell:001",
    "type": "Bell",
    "TimeInstant": "2023-09-21T13:31:45.090Z",
    "category": [
        "actuator"
    ],
    "controlledProperty": "noiseLevel",
    "function": [
        "onOff"
    ],
    "refStore": "urn:ngsi-ld:Store:001",
    "ring_info": " ring OK",
    "ring_status": "OK",
    "supportedProtocol": [
        "ul20"
    ],
    "ring": ""
}

But doing the same with LD and the equivalent static attributes category controlledProperty, function supportedProtocol are not created (but the command ones are). Any ideas?

[AlvaroVega]

@AlvaroVega - There is still currently one difference between LD and v2 provisioning - provisioning static attributes in the group. does not duplicate onto the LD context broker when an update occurs. I was wondering if createInitialEntityFake has anything to do with this?

createInitialEntityFake is doing nothing, ist just a bypass function to keep backward compatibility of previous and later methods.

[mapedraza]

This issue is not valid anymore after https://github.com/telefonicaid/fiware-orion/issues/4430#issuecomment-1896150495

Nevertheless PR #1551 should change the scope to include type URL parameter into commands documentaion.