Configure Your Devices

How to Connect Sensors to Your Application

Before using or uploading data to Oracle IoT Production Monitoring Cloud Service you must connect to your application the sensors that you are using to monitor your machines.

To follow this procedure you need access to an Oracle Internet of Things Intelligent Applications Cloud instance. Typically the URL has the form http://hostname/ui. The credentials are the same credentials you use for Oracle IoT Production Monitoring Cloud Service.

Using Oracle Internet of Things Intelligent Applications Cloud:

Create the device model for your sensors.
See Create a Device Model
Register your sensors.
See Register a Single Device and Register a Batch of Devices
Activate your sensors.
See Activate a Device and Activate a Batch of Devices.

Using Oracle IoT Production Monitoring Cloud Service:

Associate the device model with a machine type:
1. Create or edit a machine type.
  For information on how to create a machine type, see Create Machine Types.
2. In the Device Model section, click Create New .
3. Enter a name to identify this device model.
4. (Optional) In the Instructions field, enter a description.
5. (Optional) Select Required if it’s mandatory to define a device that uses this device model when creating a new machine.
6. From the Device Model list, select the device model you want to assign to this machine type.
7. Click OK.
Associate a specific sensor with a specific machine:
1. Create or edit a machine.
  For information on how to create a machine, see Create Machines.
2. In the Sensor Device section, click Find Device for the device model that corresponds to the sensor you want to associate to this machine.
3. From the Property list, select a search parameter to search for this sensor, then enter the value for this search parameter, and click Go.
  The available sensors appear in the list below the search fields.
4. Select a sensor from the list.
5. Click Select.

Create a New Device Model

A device model is an interface that lets any device communicate with Oracle Internet of Things Intelligent Applications Cloud regardless of its manufacturer or operating system.

Open the Oracle Internet of Things Intelligent Applications Cloud Management Console.

You can access the Oracle Internet of Things Intelligent Applications Cloud Management Console from the following URL:

https://hostname/ui

Here, hostname is the host name of your Oracle Internet of Things Intelligent Applications Cloud instance.
Click the Menu () icon.
Select Devices and then select Model.
Select one of these options:
- If you have not previously created a device model, click Create Device Model.
- If you have previously created a device model, click the Add () icon.
Complete these fields:
1. Name: Enter a name for the device model.
2. Description: Enter an optional description for the device model.
3. URN: Enter a unique identifier for the device model. Use this format: urn:com:<mycompany>:<mydevice>:<what the device model does>.
Select system attributes for the device model.
(Optional) Add custom attributes for the device model:
1. Expand the Custom Attributes option list.
2. Click the Add () icon.
3. Enter a name for the custom attribute in the Name field.
4. Enter an optional description for the custom attribute in the Description field.
5. Select a data type in the Type list.
6. Select Writable if you want to make the custom attribute writable.
7. Click OK.
(Optional) Define the actions that can be invoked on the device:
1. Expand the Actions option list.
2. Click the Add () icon.
3. Enter a name for the action in the Name field.
4. Enter an optional description for the action in the Description field.
5. Select the data type for the action in the Arguments list.
6. Enter an optional alternate name for the action in the Alias field.
7. Click OK.
(Optional) Create alerts and custom message formats for the device model:
1. Expand the Alerts and Custom Messages option list.
2. Click the Add () icon.
3. Enter a name for the alert or custom message in the Name field.
4. Enter an optional description for the alert or custom message in the Description field.
5. Enter a unique identifier for the alert or custom message in URN field. Use this format:urn:<mycompany>:<department>:<mydevice>:<device model>:<message>.
6. Select a data type in the Type list.
7. Click OK.
8. Select the alert message format and then click the Add () icon in the Fields column.
9. Enter a name for the message type in the Name field.
10. Select a data type in the Type list.
11. Select Optional to indicate the field value can be missing in the device model message format.
12. Click OK.
Click Save.

Predefined Device Models

Oracle IoT Production Monitoring Cloud Service provides predefined device models to report the state of a machine or the production output for a product.

The following Oracle IoT Production Monitoring Cloud Service device models are included in Oracle Internet of Things Intelligent Applications Cloud:

Machine State (ProductionMonitoringMachineState)

A sensor attached to your machine can use this device model to report the state of the machine to Oracle Internet of Things Intelligent Applications Cloud. The states can be one of the following:

INUSE
DOWN
IDLE

If the sensors connected to the machine are not capable of reporting the state themselves, a connected gateway device can be used to report on behalf of the sensor.

The device model specification is as follows:

{
  "urn": "urn:com:oracle:iot:pm:machine_state",
  "name": "Production Monitoring Machine State device model",
  "description": "Machine state device model",
  "system": true,
  "attributes" : [
     {
       "name" : "state",
       "description" : "Machine state enum. This is one of INUSE, DOWN or IDLE",
       "type": "STRING",
       "writable" : false
     },
     {
       "name" : "machine",
       "description" : "Machine Unique Identifier",
       "type": "STRING",
       "writable" : false
     }
  ]
}

The following table describes the attributes used in the device model:

Attribute	Type	Description	Required	Default Value
machine	String	The identifier of the machine for which the state information is being reported. Populated only if the message is sent by a gateway on behalf of the machine. If a device that implements this device model is associated with the machine (as a device attribute), then `machineId` is derived from the device's `sourceId`.	No	none
state	String	The physical state of the machine: `INUSE`: Machine is up and running, and is actively producing a product. `DOWN`: Machine is not running; could be down on account of a scheduled maintenance, outage, or hardware failure. `IDLE`: Machine is running, but not actively producing any product.	Yes	none

Production Output (ProductionMonitoringProductionOutput)

Use this device model to report the production output for a product for the specified time period. The device model specification is as follows:

{
    "urn": "urn:com:oracle:iot:pm:production_output",
    "name": "Production Monitoring Production Output device model",
    "description": "Production Output device model",
    "system": true,
    "attributes" : [
        {
            "name" : "startTime",
            "description" : "Start time of the production output. This is specified as a Long value in milliseconds since epoch (Jan 1 1970)",
            "type": "DATETIME",
            "writable" : false
        },
        {
            "name" : "endTime",
            "description" : "End time of the production output. This is specified as a Long value in milliseconds since epoch (Jan 1 1970). The value should be greater than the startTime attribute.",
            "type": "DATETIME",
            "writable" : false
        },
        {
            "name" : "product",
            "description" : "Product Identifier that was produced.",
            "type": "STRING",
            "writable" : false
        },
        {
            "name" : "quantity",
            "description" : "Quantity of the product produced. This should be within the range [1,Integer.MAXINT] (both inclusive)",
            "type": "INTEGER",
            "writable" : false
        },
        {
            "name" : "factory",
            "description" : "Factory where the product was produced. The value specified should be a registered factory identifier.",
            "type": "STRING",
            "writable" : false
        },
        {
            "name" : "productionLine",
            "description" : "Production Line within the factory where the product was produced. The value specified should be a registered production line identifier.",
            "type": "STRING",
            "writable" : false
        },
        {
            "name" : "routingTask",
            "description" : "The routing task associated with the produced product. The value specified should be a registered routing task identifier.",
            "type": "STRING",
            "writable" : false
        },
        {
            "name" : "machine",
            "description" : "The machine which produced the product. The value specified should be a registered machine identifier.",
            "type": "STRING",
            "writable" : false
        }
    ]
}

The following table describes the attributes used in the device model:

Attribute	Type	Description	Required	Default Value
startTime	DateTime	Start time of the production output, specified as a `Long` value in milliseconds since epoch (Jan 1 1970).	Yes	none
endTime	DateTime	End time of the production output, specified as a `Long` value in milliseconds since epoch (Jan 1 1970). The value should be greater than the startTime attribute.	Yes	none
product	String	Product identifier for the product that was produced.	Yes	none
quantity	Integer	Quantity of the product produced. This should be within the range `[1,Integer.MAXINT]` (both inclusive).	Yes	none
factory	String	Factory where the product was produced. The value specified should be a registered factory identifier.	No At least one of factory, productionLine, routingTask, or machine is required.	none
productionLine	String	Production line within the factory where the product was produced. The value specified should be a registered production-line identifier.	No At least one of factory, productionLine, routingTask, or machine is required.	none
routingTask	String	The routing task associated with the product. The value specified should be a registered routing-task identifier.	No At least one of factory, productionLine, routingTask, or machine is required.	none
machine	String	The machine which produced the product. The value specified should be a registered machine identifier.	No At least one of factory, productionLine, routingTask, or machine is required.	none

Register a Single Device

To communicate with Oracle Internet of Things Cloud Service, every device that is connected to Oracle Internet of Things Cloud Service must be registered and then activated. All devices are registered as a Directly Connected Device (DCD). During activation, the device indicates support for indirect enrollment. A device indicating indirect enrollment capability is automatically changed from DCD to gateway.

Click the Menu () icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
Click Devices.
Click Registration.
Click Register Single Device.
Complete the optional and mandatory fields.

Note:
If you leave the Activation Secret field blank, a value is auto-generated and displayed when the device registration is confirmed. You can enter your own Activation Secret value. Any additional information, such as Name, Description, and Metadata are optional, but can be useful as search criteria when managing your registered devices.
Click Register.
Enter a password in the File Protection Password field to encrypt the provisioning file that contains the configuration and credentials to activate your device.
Enter the password again in the Confirm Password field.
Download the provisioning file:
1. Click Download Provisioning File.
2. Click Save File.
3. Click OK.
4. Browse to a location to save the provisioning file.
5. Click Save.
Click Finish.

Register a Batch of Devices

Registering a batch of devices reduces the time required to register multiple devices. You create a comma-separated values (CSV) file to define the settings for each device. You upload the CSV file to Oracle Internet of Things Intelligent Applications Cloud.

To view the information that you should include in the CSV file, see About CSV Batch Registration File Properties.

Click the Menu () icon adjacent to the Oracle Internet of Things Intelligent Applications Cloud title on the Management Console.
Click Devices.
Click Registration.
Select one of these options:
- Click Download CSV template to download a CSV template that you can complete.
  
  Note:
  The CSV file contains the mandatory and optional property values for each device. If a value is not provided for the optional properties, insert a comma to indicate that a value is not provided. In the last line of the sample CSV file, a comma indicates that property values are not provided for ActivationId and Activation Secret
- Click Batch Registration to upload an existing CSV file.
Click Browse and browse to the CSV file that contains the registration information for the devices you are registering.
Click Next when the CSV registration file is successfully uploaded.
If the Review page contains a warning () icon, select one of these options:
- Update - Choose this option if you want to update the information for an existing registered device. The registered device has the same manufacturer, model and serial number as one of the devices listed in the CSV registration file.
- Ignore - Choose this option if you do not want to include the device in the current registration process.
Click one of these options:
- Next: Click to proceed to register the items in the CSV registration file that have been identified as being viable candidates for registration.
- Cancel: Click to discontinue the batch registration process.
Enter a password in the File Protection Password field to encrypt the provisioning file that contains the configuration and credentials to activate your device.
Enter the password again in the Confirm Password field.
Download the provisioning file:
1. Click Download Provisioning File.
2. Click Save File.
3. Click OK.
4. Browse to a location to save the provisioning file.
5. Click Save.
Click Finish.
Activate the registered devices to begin a secure communication between the devices and Oracle Internet of Things Intelligent Applications Cloud. See Activate a Batch of Registered Devices.

About CSV Batch Registration File Properties

The following table provides descriptions of the properties that appear in the Comma Separated Values (CSV) file used to register a batch of devices with Oracle Internet of Things Intelligent Applications Cloud. Mandatory and optional values are described in the table and are listed in the order they are expected to appear in the CSV file.

To register a batch of devices with Oracle Internet of Things Intelligent Applications Cloud, see Registering a Batch of Devices.

Property	Required / Optional	Description
`Name`	Optional	The `String` data type assigned to the registered device. This value can be modified after device registration.
`Manufacturer`	Required	The manufacturer of the device.
`Model Number`	Required	The model number of the device
`Serial Number`	Required	The serial number of the device.
`Activation ID`	Optional	A Device Unique Identifier (UID) that is required for device activation. If a value is not specified, an auto-generated value is assigned to the device after a successful registration. The value cannot be changed after the device is successfully registered.
`Activation Secret`	Optional	The Activation Secret (also known as Shared Secret) value required to activate your device. If a value is not specified, an auto-generated string value is assigned to the device after a successful registration. This value is available after a successful registration. This value can be modified before you modify your device.
`Latitude`	Optional	The decimal notation of the latitude of the device’s position. For example: -43.5723 [World Geodetic System 1984]. If you specify the latitude, then you must also specify the longitude.
`Longitude`	Optional	The decimal notation of the longitude of the device’s position. For example: , e.g. -43.5723 [World Geodetic System 1984]. If you specify the longitude, then you must also specify the latitude.
`Altitude`	Optional	The decimal notation of the altitude of the device’s position, in meters above sea level.
`Accuracy`	Optional	The accuracy of the device’s position in meters. This must be a positive number or zero. An accuracy value can only be specified if the latitude and longitude are provided.
`Metadata`	Optional	Key/value pairs that are listed in successive columns. There must be an even number of columns containing keys and values. If there is an odd number of columns, an error message is returned.

Activate a Device

A device can be activated after it is registered and an application has been created and run on the device. During activation, the device indicates support for indirect enrollment. A device indicating indirect enrollment capability is automatically changed from DCD to Gateway.

Register your directly connected device. See Registering a Single Device.
Create an application for the device using the Oracle Internet of Things Intelligent Applications Cloud Client Software Library APIs. See Developing Device Software Using the Client Software Libraries.
When using the Java Client Library, for example, use the following steps to initialize and activate the device:
1. Add this statement to the device application code to initialize the device:
```
DirectlyConnectdDevice dcd = new DirectlyConnectedDevice(configFilePath, configFilePassword);
```
2. Add this statement to the device application code to activate the device:
```
if (!dcd.isActivated())
{ dcd.activate(deviceModelUrn); }
```
Verify the device has been activated:
1. Open the Oracle Internet of Things Intelligent Applications Cloud Management Console.
2. Click the Menu () icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
3. Click Devices.
4. Click Management.
5. Locate the device in the device table or use the Property and Value fields at the top of the table to search for a specific device.
6. Verify Activated and not Registered is displayed in the State column.

Activate a Batch of Registered Devices

After you’ve registered a batch of devices, you need to activate the devices before they can securely communicate with Oracle Internet of Things Intelligent Applications Cloud.

Register the devices and download the provisioning file. See Registering a Batch of Devices.
Activate each of the registered devices. See Activate a Device.
Verify that each of the registered devices has been activated.
1. Open the Oracle Internet of Things Intelligent Applications Cloud Management Console.
2. Click the Menu () icon adjacent to the Oracle Internet of Things Cloud Service title on the Management Console.
3. Click Devices.
4. Click Management.
5. Locate the device in the device table or use the Property and Value fields at the top of the table to search for a specific device.
6. Verify Activated and not Registered is displayed in the State column.