Create and Configure Connectors

Connectors manage the connection and communication with devices or with third-party cloud services. They also process the metadata and telemetry data from the devices or the services.

Oracle Internet of Things Cloud Service provides multiple built-in connectors that allow declarative configuration to connect with third-party cloud services or network providers.

Types of Built-in Connectors

Use the Oracle Internet of Things Cloud Service management console to configure the following built-in connectors:

  • Generic: Use this connector for all devices that can communicate over HTTP or MQTT, and have a basic authentication mechanism. You can also create a generic connector for an Orange or a Proximus network.
  • OrangeLora: Use this connector when your devices' network provider is Orange and the devices are deployed in a LoRa network.
  • ProximusLora: Use this connector when your devices' network provider is Proximus and the devices are deployed in a LoRa network.

Before you can start a connector that integrates devices in an external network or cloud service, you need to configure a stream in the network provider's server. When you configure this stream, you provide the URL of your Oracle Internet of Things Cloud Service instance, authentication information, stream format, and other required details.

Create an HTTP Server Connector

Create an HTTP Server connector when your network provider is other than Orange or Proximus. You can also customize an HTTP Server connector for devices in an Orange or Proximus network.

An HTTP Server connector is a generic connector. You'll need the user name and password for basic authentication. The user should have the administrator role in the Oracle Internet of Things Cloud Service instance. For an MQTT Client connector, you'll also need the MQTT broker URL, the client ID, and the topic name.
  1. Open the Oracle Internet of Things Cloud Service management console.
  2. Click Menu Menu icon.
  3. Click Devices, and then click Connectors.
  4. On the Connectors page, click Create New Connector Create New Connector.
  5. Enter values in the Name and Description fields.
  6. Select 1 in the Scale Factor field if you need only one instance of the connector.
  7. In the Type field, select HTTP Server.
  8. In the Telemetry section, select the appropriate values.
    • Envelope: Click Add Grammar, and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted envelope data.
    • Payload encoding: If your payload is in JSON, select asciihex. if your payload is in base64-encoded binary, select base64 .
  9. (Optional) Configure the Discovery section when the third-party network provider has provided a REST endpoint to retrieve additional device metadata. You can use this metadata to specify the selection criteria of an interpreter.
    • Protocol: Select Https.
    • URL: Enter the URL of the REST endpoint to retrieve data.
    • Authentication: Select Basic authentication, HTTP Header or HTTP Query.
      • For Basic authentication, enter values in the User name and Password fields. The user must have administrative access.
      • For HTTP header, click headers, enter the key and the value, and then click OK.
      • For HTTP query, click parameters, enter the key and the value, and then click OK.
    • Device metadata: Click Add Grammar and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted data.
  10. Click Save. When you receive the message Saved successfully, click Back.
    On the Connectors page, the HTTP Server connector is listed and the State field displays the status of the connector. The five states are STARTING, STARTED, FAILED, STOPPING, and STOPPED. STARTED indicates that the connector is ready to accept device data.
    • To modify your HTTP Server connector, click Edit Edit.
    • To remove the HTTP Server connector, click Delete Delete.
    • To create an instance of your HTTP Server connector, click Start Start.

      Note:

      The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.
    • To view the device notifications that the connector receives, click connectors_messageALERTalert .

      Note:

      On the Notifications page, click the data under Content to view the device information. You can also create an interpreter from this page when device data is received for the first time. See Configure Interpreters at Runtime.
    • To view the details of your connector, click View View.

Create an MQTT Server Connector

Create an MQTT Server connector when you have a client which is a device or a network server that publishes telemetry over MQTT protocol.

To create and use an MQTT Server connector, you'll also need a sample payload that will be published.
  1. Open the Oracle Internet of Things Cloud Service management console.
  2. Click Menu Menu icon.
  3. Click Devices, and then click Connectors.
  4. On the Connectors page, click Create New Connector Create New Connector.
  5. Enter values in the Name and Description fields.
  6. Select 1 in the Scale Factor field if you need only one instance of the connector.
  7. In the Type field, select MQTT Server.
  8. In the Telemetry section, select or enter the appropriate values.
    • Notice that the Host, MQTT Port, WebSocket Port, and Context Path fields. are populated for you.
    • Topic: Modify the default value to specify the MQTT topic that your client would publish into.
    • Envelope: Click Add Grammar, and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted envelope data.
    • Payload encoding: If your payload is in JSON, select asciihex. if your payload is in base64-encoded binary, select base64 .

    Note:

    When you configure an MQTT client to connect to the Oracle IoT MQTT Server Connector, you need to provide the Oracle Identity Cloud Service (idcs) credentials of a user having an administrator role in the Oracle Internet of Things Cloud Service instance. Enter the username as <connector-name>/<idcs-user> and password as <idcs-password>.
  9. (Optional) Configure the Discovery section when the third-party network provider has provided a REST endpoint to retrieve additional device metadata. You can use this metadata to specify the selection criteria of an interpreter.
    • Protocol: Select Https.
    • URL: Enter the URL of the REST endpoint.
    • Authentication: Select Basic authentication, HTTP Header or HTTP Query.
      • For Basic authentication, enter values in the User name and Password fields.
      • For HTTP header, click headers, enter the key and the value, and then click OK.
      • For HTTP query, click parameters, enter the key and the value, and then click OK.
    • Device metadata: Click Add Grammar and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted data.
  10. Click Save. When you receive the message Saved successfully, click Back.
    On the Connectors page, the MQTT Server connector is listed and the State field displays the status of the connector. The five states are STARTING, STARTED, FAILED, STOPPING, and STOPPED. STARTED indicates that the connector is ready to accept device data.
    • To modify your MQTT Server connector, click Edit Edit.
    • To remove the MQTT Server connector, click Delete Delete.
    • To create an instance of your MQTT Server connector, click Start Start.

      Note:

      The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.
    • To view the device notifications that the connector receives, click Notificationsalert .

      Note:

      On the Notifications page, click the data under Content to view the device information. You can also create an interpreter from this page when device data is received for the first time. See Configure Interpreters at Runtime.
    • To view the details of your MQTT Server connector, click View View.

Create an MQTT Client Connector

Create an MQTT Client connector when your network provider subscribes to an MQTT broker and is other than Orange or Proximus. You can also customize a HTTP Server connector for devices in an Orange or Proximus network.

For an MQTT Client connector, you'll also need the MQTT broker URL, the client ID, and the topic name.
  1. Open the Oracle Internet of Things Cloud Service management console.
  2. Click Menu Menu icon.
  3. Click Devices, and then click Connectors.
  4. On the Connectors page, click Create New Connector Create New Connector.
  5. Enter values in the Name and Description fields.
  6. Note:

    The distribution of messages to the individual connector instances is a function of the MQTT broker and is not determined by the connector. Some brokers evenly distribute messages across each connector instance, while some duplicate messages to each instance. If the MQTT broker cannot distribute messages evenly across the instances, then use a single scale instance of the connector.

    Select 1 in the Scale Factor field if you need only one instance of the connector.
  7. In the Type field, select MQTT Client.
  8. In the Telemetry section, select the appropriate values.
    • Complete the MQTT Broker URL, Client ID, and Topic fields.
    • Authentication:
      • For Basic authentication enter your user name and password.
      • For HTTP header, click headers, enter the key and the value, and then click OK.
    • Envelope: Click Add Grammar, and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted envelope data.
    • Payload encoding: If your payload is in JSON, select asciihex. if your payload is in base64-encoded binary, select base64 .
  9. (Optional) Configure the Discovery section when the third-party network provider has provided a REST endpoint to retrieve additional device metadata. You can use this metadata to specify the selection criteria of an interpreter.
    • Protocol: Select Https.
    • URL: Enter the URL of the REST endpoint.
    • Authentication: Select Basic authentication, HTTP Header or HTTP Query.
      • For Basic authentication, enter values in the User name and Password fields.
      • For HTTP header, click headers, enter the key and the value, and then click OK.
      • For HTTP query, click parameters, enter the key and the value, and then click OK.
    • Device metadata: Click Add Grammar and add the details in the Grammar window. See Learn About Adding Grammars. Ensure that you use the Map field to map the required device metadata fields with the values of the interpreted data.
  10. Click Save. When you receive the message Saved successfully, click Back.
    On the Connectors page, the MQTT Client connector is listed and the State field displays the status of the connector. The five states are STARTING, STARTED, FAILED, STOPPING, and STOPPED. STARTED indicates that the connector is ready to accept device data.
    • To modify your MQTT Client connector, click Edit Edit.
    • To remove the MQTT Client connector, click Delete Delete.
    • To create an instance of your MQTT Client connector, click Start Start.

      Note:

      The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.
    • To view the device notifications that the connector receives, click connectors_messageALERTalert .

      Note:

      On the Notifications page, click the data under Content to view the device information. You can also create an interpreter from this page when device data is received for the first time. See Configure Interpreters at Runtime.
    • To view the details of your MQTT Client connector, click View View.

Create an OrangeLora Connector

You create an OrangeLora connector for devices deployed in a LoRa network provided by Orange

Before you create the connector, you should have the value of the API key of the Orange live objects that is needed for authentication.
  1. Open the Oracle Internet of Things Cloud Service management console.
  2. Click Menu Menu icon.
  3. Click Devices and then click Connectors
  4. On the Connectors page, click Create New Connector Create New Connector.
  5. Enter the values in the Name and Description fields.
  6. In the Scale Factor field, select 1 .
  7. In the Type field, select OrangeLora.
  8. In the API Key field, enter the API key for the Orange live objects.
  9. Click Save. When you receive a messagesaved successfully, then click Back.
    On the Connectors page, your OrangeLora connector is listed and its State is displayed.
    • To modify any of the fields of your OrangeLora connector, click Edit Edit.
    • To remove the OrangeLora connector, click Delete Delete.
    • To create an instance of your OrangeLora connector, click Start Start.

      Note:

      The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.
    • To view the notifications received by the connector, click connectors_messageALERTalert .
    • To view the details of your OrangeLora connector, click View View.

Create a ProximusLora Connector

You create a ProximusLora connector for devices deployed in a LoRa network provided by Proximus. It is an HTTP Server type connector.

Before you create the connector, you should have the user name and password that is needed for basic authentication.
  1. Open the Oracle Internet of Things Cloud Service management console.
  2. Click Menu Menu icon.
  3. Click Devices, and then click Connectors.
  4. On the Connectors page, click Create New Connector Create New Connector.
  5. Enter the values in the Name and Description fields.
  6. In the Scale Factor field, select 1.
  7. In the Type field, select ProximusLora.
  8. In the Connection section, ensure that the value for HTTP URL is the one that you entered when you configured the Proximus stream.
  9. In the Authentication section, enter the user name and password.
  10. Click Save. When you receive a message saved successfully, then click Back.
    On the Connectors page, your Proximus connector is listed and its State is displayed.
    • To modify any of the fields of your Proximus connector, click Edit Edit.
    • To remove the Proximus connector, click Delete Delete.
    • To create an instance of your Proximus connector, click Start Start.

      Note:

      The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.
    • To view the notifications received by the connector, click connectors_messageALERTalert .
    • To view the details of your Proximus connector, click View View.