When a device create request is received from the CMS, the IDL calls the IDI (IDL Driver Instance) OnDevCreate callback function that was registered during the init process.
Callback_index is of no significance to the IDI. It must be passed as is back to the IDL when calling
The “args” passed to the IDI device create callback function is the stringified “args” JSON object that is received in the actual MQTT request for device creation, which contains some or all of the following fields:
- unid - this is the UNID of the device to be created and it must be verified for correctness by the IDI for the following reasons:
- It is assumed that create requests will be issued from the CMS, and thus unid uniqueness will be verified before sending the create request. However, there are certain corner cases that must be handled by the IDI. For example, in Modbus RTU, unid strings “01:05” and “01:5” both mean the same thing, but this is not caught by the CMS because the strings are different. This is protocol specific, and it must be handled in the IDI.
- The IDI must also verify that the UNID is valid. For example, Modbus RTU can have slave IDs in the range of 1-255 only. Modbus TCP unid can have IP addresses separated by dots or hyphens or commas. Parsing of the IP address and making sense of it will be the responsibility of the IDI.
- type - This is the program_ID of the device to be created. This needs to be checked by the IDI because a protocol can have its own type check rules. For example, Modbus requires that the channel type must be 0xDB for Modbus RTU and 0xDC for Modbus TCP. For any other channel type in the PID, Modbus Engine throws an error and device creation fails.
- args - can also contain “implementation” and “routing” properties in create action which are protocol specific. The IDL will ignore these fields and let the IDI make sense of it.
xif_dp_array is currently passed as NULL. In future versions of IDL, this will contain the stringified JSON array of the datapoints obtained after parsing the XIF file. This will contain protocol specific information for the datapoints that IDL did not interpret. The IDI driver process will be responsible to parse this array and link the information to the main device and datapoint structures.
When the IDL calls the device create callback function, the IDI performs protocol specific device creation. If there is any protocol specific device data that needs to be linked to the IDL device structure, it can be linked to
void *idiDevData within
IdlDev. It can also link any protocol specific datapoint data to individual datapoints to
void *idiDpData within
Upon completion, the IDI must call
IdlDevCreateResult with the
callback_index, pointer to
IdlDev, and the appropriate
idlError (see Error Codes).
Device Create Callback Function
IdlErrorCodes OnDevCreate(int callback_index, IdlDev *dev, char *args, char *xif_dp_array);
Device Create Related Functions
void IdlDevCreateCallbackSet(Idl *idl, int (*OnDevCreate)(int, IdlDev *, char *, char *));
Must be called by IDI prior to calling
void IdlDevCreateResult(int callback_Index, IdlDev *dev, int idlError);
Must be called at the end of the callback function before exiting.