Use Direct Data Ingestion for Your Sensor Attributes

Your digital twin entities are now directly addressable over the network, using standard protocols, authentication mechanisms, and payload formats. Ingest IoT data from directly connected devices, gateways, and network servers directly into your asset and machine sensor attributes.

Choose direct ingestion to eliminate the need for registering devices and device models, and for creating IoT messages.

Use standard HTTP or MQTT protocol to send sensor data in JSON or CSV format. The application supports mutual authentication using certificates in addition to basic authentication.

The application lets you download ready-to-use schema samples for your entities. If you have custom payloads, use the interpreter editor interface to create the mappings and routing.

Set Direct Data Options for Your Entity

Use the Create Asset/Machine or Edit Asset/Machine page to set direct data options for the sensor attributes of an entity.

1. On the Create Asset/Machine or Edit Asset/Machine page, set the Data Source for one or more sensor attributes to Direct.
   
   

   

   
   

   The preceding image shows an asset editor page with two sensor attributes, Temp and Humidity. The data source for the sensor attributes is set to Direct.

   
   

   

   
   

   The preceding image shows a machine editor page with a sensor attribute, RPM and a control attribute, Overheat. The data source for the attributes is set to Direct.

2. Select Direct Data Source Options from the page menu.
   
   

   

   
   
3. Select the Data Source:

   • Direct: Use for devices that can directly connect with the application.

     • External ID: You can enter the external identifier for the device. This is usually the Hardware ID. If you do not enter a value, the default entity ID is used for authentication.

     • Authentication: Select between Client Certificate and Client ID/Secret.

       Client certificate is the recommended option for increased security. The default Common Name used for client certificate is the entity ID. If you have specified an External ID, then this is used as the common name.

       If using Client ID/Secret, specify a secure password in the Secret field. The default Client ID used for client certificate is the entity ID. If you have specified an External ID, then this is used as the client ID.

     • Payload: Select Schema if you are using the standard schema format for data ingestion. Select Custom if the payload does not follow the schema. If choosing the custom option, you must specify a previously created Interpreter to interpret the payload.

   • Direct via Any Connector: Use for devices that connect using a connector.

     External ID: You can enter the external identifier for the device. This is usually the Hardware ID. If you do not enter a value, the default entity ID is used for authentication.

   • Direct via Specific Connector: Use for devices that can connect using the specified connector.

     • Connector: Select a connector that you have previously created.

     • External ID: You can enter the external identifier for the device. This is usually the Hardware ID. If you do not enter a value, the default entity ID is used for authentication.

4. Click OK, and then click Save in the Entity editor.

Download Schema for an Entity Type

Download the JSON or CSV schema for an entity type from the Asset Types page.

1. From the Menu > Design Center > Asset Types page, select the asset type for which you wish to download the schema.
2. Select Direct Data Source Information from the Asset Types menu.

   
   
   

3. Select JSON Schema or CSV format.

   Choose the schema format that your devices would use to send data for entities of this type.

4. Click Download to download the schema file to your hard disk.

Generate Schema Sample for an Entity

Generate the sample schema for an entity to find connection details, such as host, endpoint, topic, and sample payload. You can edit the sample payload values to ingest data.

1. On the Asset Inventory or Machine Inventory page in Design Center, select Generate Schema Sample from the Asset/Machine Inventory menu.
   
   

   

   
   
2. Select the Entity Type.
   The entity type is the asset type or machine type.
3. Choose the payload Format.
   The available formats are JSON and CSV.
4. Select the Protocol.
   You can choose between MQTTS (Publish) and HTTP (Post). MQTTS will use the topic in addition to the host.
5. Select an Entity for which to generate the schema sample.
   The entity is an asset or machine of the selected type.
6. Under Target Attribute, select one or all the direct sensor attributes for the entity.
7. Under Target Entity, select whether the target entity information is included in the endpoint or the payload itself.
8. Under Measurement Count, choose whether the schema sample should include a Single reading or Multiple readings for the selected attribute.
9. Click Generate to generate the shcema sample.
   The schema sample is generated along with the endpoint details of the host and topic (for MQTTS). The payload section contains the generated schema for your asset or machine. For example, the following JSON payload includes sample data for sensor2, where the target entity information is included in the payload itself.

   {
       "3J39G39R2MA0": 50,
       "3J39G3A02MA0": 50,
       "sys_eventTime": 1650721170666,
       "sys_entityId": "sensor2",
       "sys_location": {
           "sys_altitude": 72,
           "sys_latitude": 37.39353247764676,
           "sys_longitude": -121.95359884794176
       }
   }

As shown in the following example for MQTTS, it is convenient to copy details, such as the host, topic, and sample payload from the Generate Schema Sample dialog.

The following example uses the HTTPS protocol:

Create a Connector

Use a connector to directly ingest data from devices, which are not directly connected.

We use the Create Connector option to create a connector from the Menu >Settings > IoT Organizations > Organization Name > Device Connections > Connectors page.

1. Click Menu (), and then click Settings.
2. Click the IoT Organizations tile, and then click your organization tile.
   
   

   

   
   
3. Click the Device Connections tile, and then click the Connectors tile.
4. Click Create Connector to create a new connector.
   
   

   

   
   
5. Select between Gateway and Network Server, and click Create.
   The OPC UA and Pi System connectors are also available for Production Monitoring, like in previous releases.
6. Specify a Name and optional Description for the connector.
7. Enter an External ID for the connector. This is usually the Hardware ID.
   The External ID is used as the common name in certificate-based mutual authentication, or as the client ID in password-based authentication.
8. Enter any optional Tags.
9. Optionally specify the location coordinates in the Location section.
10. Under the Security section, specify the Authentication method.

    Client certificate is the recommended option for increased security. The External ID that you specified is used as the common name.

    If using Client ID/Secret, specify a secure password in the Secret field. The External ID that you specified is used as the client ID.

11. Under Authorization, select the target entities for the connector.
    If you select Specific Entities, the connector can send data only for entities bound to the connector.
12. Select the Payload type.
    Select Schema if you are using the standard schema format for data ingestion. Select Custom if the payload does not follow the schema. If choosing the custom option, you must specify a previously created Interpreter to interpret the payload.
13. Click Save to save the connector.

Create an Interpreter

If you are using a custom payload where the payload does not follow the schema, you can create an interpreter to map the payload for the connector.

We use the Create Interpreter option to create a connector from the Menu >Settings > IoT Organizations > Organization Name > Device Connections > Interpreters page.

1. Click Menu (), and then click Settings.
2. Click the IoT Organizations tile, and then click your organization tile.
   
   

   

   
   
3. Click the Device Connections tile, and then click the Interpreters tile.
4. Click Create Interpreter to create a new interpreter.
   
   

   

   
   
5. Select the interpreter Type, and click Create.
   Mapping interpreters are the most common use case wherein the payload maps to a single entity type. Use Routing interpreters for scenarios where the payload maps to multiple entity types.
6. Provide a Name and optional Description for the interpreter.
7. Select the Target Entity Type.
   This is the target asset type or machine type of the entity. Note that this field is not displayed for routing interpreters where the payload can map to multiple entity types.
8. Select the Target Entity.
   This is the asset or machine for which you are ingesting and interpreting the data.
9. Select the Payload Encoding format.
   The available options are JSON and CSV.
10. Under Sample Payload Data, provide the sample JSON or CSV data and click Validate Data.
    The sample payload is checked for any syntax/validation errors.
11. In the Mappings section, complete the mappings of the payload to the schema.
    You must complete all required mappings, and any additional mappings that you may have.
    You can drag the payload keys to the appropriate target attributes. The following image shows the DeviceID payload key dragged to the EntityID attribute.
    
    

    

    
    
    The following image shows a completed mapping.
    
    

    

    
    
12. You can also choose Custom Formula to complete a mapping.
    Use the formula editor to build and complete your mapping.
    The following example shows a custom formula for mapping the DeviceID to EntityID.
    
    

    

    
    
13. Define any routing conditions for routing interpreters.
    Use the formula editor to build and complete your condition.
    The following example shows a custom formula for the routing condition.
    
    

    

    
    
    1. Select a Target Entity Type for the routing condition, and click Configure Mapping to complete any required and optional nested mappings for the condition.
       Note that you can navigate back to the main editor using the breadcrumbs that appear at the top of the editor page.
       
       

       

       
       
    2. Add more routing conditions, as required.
       The routing will apply to the first applicable routing condition. Once you define more than one condition, you can edit the ordering.
14. Click Save to save the interpreter.

Upload and Manage Certificates

As an integrator, you can upload your root certificate, and certificate hierarchy, to your IoT instance. The application can then authenticate your clients devices, gateways, and network servers using the certificate hierarchy. You can also manage your certificates, such as renew or revoke certificates in the application.

The Security area in the Settings section lets you upload and manage certificates. To upload a new certificate:

1. Click Menu (), and then click Settings.
2. Click Security on the Settings page.
3. Click Certificates.
4. Click Upload Certificate to upload a trusted certificate.

   
   
   

5. Specify a Name, optional Description, and select the PEM file to upload.
6. Click Upload.

   Oracle recommends that you use a CA certificate. Self-signed certificates are not recommended for production environments.

   Note:

   You can use the certificate generation tool to generate self-signed certificates. Select Download Certificate Generation Tool from the Certificates menu to use the same. Use ./gencert.sh help for usage information on the tool.

The certificate must be verified before coming into effect. You can choose Verify Root Certificate from the Certificates menu to verify the certificate. A verification code is generated, and you need to upload the signed certificate.

You can delegate provisioning to trusted parties by creating intermediate certificates. Create leaf certificates for your devices where the common name is the Entity Id.