Quick Start Tutorial for Oracle Internet of Things Cloud Service Using a C POSIX Application on a Raspberry Pi


Options



Before You Begin

Purpose

You'll download and build the C POSIX Client Software Library sample on a Raspberry Pi, a credit-card sized computer. Then you'll build and run a C POSIX application that simulates a device sending a message to Oracle Internet of Things (IoT) Cloud Service.

Time to Complete

Approximately 30 minutes

Background

  • This tutorial assumes that you've already performed the tasks in Setting Up a Raspberry Pi Device to Run Oracle IoT Cloud Service Software.

  • This tutorial also assumes that you've attached a keyboard and monitor to the Raspberry Pi (option 2 in the OBE tutorial Setting Up a Raspberry Pi Device to Run Oracle IoT Cloud Service Client Software). The command windows shown are those provided by the Raspberry Pi graphical user interface. You can also use telnet or another shell client such as PuTTY for Windows to access the Raspberry Pi from your host system, as described in option 1.

  • As you progress through this tutorial, you will collect configuration data. You will use the data in this tutorial, as well as in other tutorials that refer to this tutorial. The first time that configuration data appears, it's marked with an asterisk and a number. Subsequent references are marked only with the corresponding number. Use this spreadsheet to keep track of your data.

What Do You Need?

  • A desktop or laptop computer running Windows 7 or later, or Mac OS 10.9 or later, or an 86/x64 PC running Ubuntu 14.04.3 LTS (Trusty Tahr)

    Note: This tutorial assumes that you're using a Windows 7 system as your host system. If you have a system that's running native Linux, then the steps will be similar to those on the Raspberry Pi device.

  • Raspberry Pi Model B Revision 2, Model B+ or later, power supply, Ethernet cable.
  • A USB/TTY cable (see Option 1: Configuring SSH by Using a USB/TTY Cable), or a USB keyboard and mouse and an HDMI cable and monitor (see Option 2: Configuring the Raspberry Pi for a GUI Login).
  • One of the following supported browsers on your host system: Firefox 31 or later, Internet Explorer 11 or 12, Safari 7 or 8. You may use the Epiphany web browser on the Raspberry Pi.

Accessing Your Oracle IoT Cloud Service

  1. Open the URL*1 for your IoT Cloud Service in a web browser.

    You can find this URL in the email you received when you purchased your subscription to Oracle Internet of Things Cloud Service. Typically this URL has the form https://myinstance-myidentitydomain.iot.us.oraclecloud.com/ui.

  2. Log in using your credentials.

    The e-mail that you received when you purchased your subscription also contains the user name and password to access the service.

    The Home page for the Oracle IoT Cloud Service appears.

Creating the HelloWorld Application

  1. Click on the Main Menu, then click Browse Applications, then click Create Application.

    The Create Application dialog appears.

    Shows how to create a new application.
    Description of this image
  2. Enter the following values and then click Create:

    • Name: HelloWorld
    • Description: Shows how to send a Hello World message

    The Applications page appears. The Applications page contains a list of all the existing applications.

  3. Click the HelloWorld application.

    The Device Model page for this application appears.

    Shows how to create a new application.
    Description of this image
  4. Click Create Device Model.

    Shows how to create a new device model.
    Description of this image

    The New Device Model page appears.

  5. In the Details section, enter the following values:

    • Name: HelloWorld-DeviceModel
    • Description: Device model for the C POSIX HelloWorld application
    • URN: urn:test:posix:helloworld*2
    Shows how to fill in the New Device Model page.
    Description of this image
  6. In the Custom Attributes section, click the Add button, and enter the following values:

    • Name: message*3
    • Description: This attribute stores the Hello World message.
    • Type: String
    Shows the Add Attribute dialog.
    Description of this image
  7. Click OK.

  8. Click Save.

    The custom attribute is saved and the Device Model page appears.

  9. Click in the Main menu, then Applications to go back, then Devices.

  10. Click the Registration menu item on the left side of the page.

    Registration menu
    Description of this image
  11. In the Single Registration section, click Register Single Device.

    Register single device
    Description of this image
  12. On the Single Device Registration page, enter the following values, and then click Register:

    • Activation ID: AAAAAAQB7RGA-B4
    • Activation Secret: MySecret*4
    • Name: Hello-World-Device
    • Manufacturer: Message Factory
    • Serial Number: 123456789
    • Model Number: M-12345
    Single device registration
    Description of this image

    Note: The field Activation ID must be completed. You can leave the Activation Secret field blank to be auto-generated.

  13. A confirmation page is displayed.

    Registration successful
    Description of this image

    Specify a password in the File Protection Password and in Confirm Password fields and then click in Download Provisioning File button and save the file, it has this name: AAAAAAQB7RGA-B4-provisioning-file.conf. Note that password, you will need it and the downloaded file to connect your device to Oracle IoT Cloud Service.

  14. Click Finish.

Configuring Your Simulated Device

  1. Open a terminal window on the Raspberry Pi and ensure that the date and time are correct by using the date command:

    date

    If the date or time isn't correct, ensure that your Raspberry Pi has access to the Internet, as explained in Configuring the Raspberry Pi for Internet Access, in the OBE Setting Up a Raspberry Pi Device to Run Oracle IoT Cloud Service Software.

  2. Enter the following command. If you're asked if you want to continue during the installation, answer Y.

    sudo apt-get install libssl-dev

    Raspberry pi console
    Description of this image
  3. Enter the following command:

    export IOTCS_OS_NAME="Raspbian GNU/Linux"

    The variable os_name is a name used to get the activation policy.

  4. Enter the following command:

    export IOTCS_OS_VERSION="8"

    The variable os_version is a number used to get the activation policy.

  5. Click the earth icon to open the Epiphany web browser. If you aren't in graphical mode, then enter startx to start the GUI.

    Raspberry Pi web browser icon
    Description of this image
  6. Open the Oracle IoT Cloud Service Client Software Library downloads page.

  7. Locate the Binary file for C POSIX Client Software Library and download the zip file to your home directory (/home/pi) by right-clicking and selecting Save Link As.

    The name of the zip file is iot-csl-posix-bin-release.zip, where release is the release and version number (that is, 16.2.3.0.0-8). In the download site, the version in the release number might be different.

    C POSIX Client Software Library download
    Description of this image
  8. Use the unzip command to extract the content of the iotcs-csl-posix-bin-release.zip file.

    Raspberry pi console
    Description of this image

    The files are extracted into the subdirectory iotcs.

Sending Your First Message

  1. In the bin directory, create a C POSIX program hello_world_sample.c and use the following code to create a basic simulator application.

    /*
     * An example of a directly connected device which is capable of communicating
     * directly with Oracle IoT Cloud Service. This sample illustrates 
     * C code for sending data to the cloud service and does not fully explore the Client Library API.
     *
     * The sample uses the virtualization API. It presents a simple messenger.
     *
     * Device implements a device model. A device model is a set of related
     * attributes, actions, and message formats that can be represented in
     * a real device. For this example the "Hello World" device model is used.
     * This device model must be uploaded to the server before running this example.
     */
     
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include <unistd.h>
     
    /* include common public types */
    #include "iotcs.h"
    /* include iot cs device model APIs */
    #include "iotcs_virtual_device.h"
    /* include methods for device client*/
    #include "iotcs_device.h"
     
    /* Current device value */
    static const char* device_current_value;
    /* Device model handle */
    static iotcs_device_model_handle device_model_handle = NULL;
    /* Device handle */
    static iotcs_virtual_device_handle device_handle = NULL;
     
    /* print error message and terminate the program execution */
    static void error(const char* message) {
        printf("Error occurred: %s\n", message);
        exit(EXIT_FAILURE);
    }
     
    int main(int argc, char** argv) {
        /* This is the URN of your device model. */
        const char* device_urns[] = {
            "urn:test:posix:helloworld",
            NULL
        };
     
        iotcs_result rv;
     
        if (argc < 3) {
            error("Too few parameters.\n"
                    "\nUsage:"
                    "\n\tdirectly_connected_device.out path password"
                    "\n\tpath is a path to trusted assets store."
                    "\n\tpassword is a password for trusted assets store.");
        }
        const char* ts_path = argv[1];
        const char* ts_password = argv[2];
      
        /*
         * Initialize the library before any other calls.
         * Initiate all subsystems like ssl, TAM, request dispatcher,
         * async message dispatcher, etc which needed for correct library work.
         */
      
        if (iotcs_init(ts_path, ts_password) != IOTCS_RESULT_OK) {
            error("Initialization failed");
        }
     
        /*
         * Activate the device, if it's not already activated.
         * Always check if the device is activated before calling activate.
         * The device model URN is passed into the activate call to tell
         * the server the device model(s) that are supported by this
         * directly connected device
         */
     
        if (!iotcs_is_activated()) {
            if (iotcs_activate(device_urns) != IOTCS_RESULT_OK) {
                error("Sending activation request failed");
            }
        }
     
        /* get device model handle */
        if (iotcs_get_device_model_handle(device_urns[0], &device_model_handle) != IOTCS_RESULT_OK) {
            printf("iotcs_get_device_model_handle method failed\n");
            return IOTCS_RESULT_FAIL;
        }
     
        /* get device handle */
        if (iotcs_get_virtual_device_handle(iotcs_get_endpoint_id(), device_model_handle, &device_handle) != IOTCS_RESULT_OK) {
            printf("iotcs_get_device_handle method failed\n");
            return IOTCS_RESULT_FAIL;
        }
     
        /* set device value */
        rv = iotcs_virtual_device_set_string(device_handle, "message", "Hello world!");
     
        if (rv != IOTCS_RESULT_OK) {
            printf("iotcs_virtual_device_set_string method failed\n");
            return IOTCS_RESULT_FAIL;
        }
     
        /* get current device value */
        if (iotcs_virtual_device_get_string(device_handle, "message", &device_current_value) != IOTCS_RESULT_OK) {
            printf("iotcs_virtual_device_get_string method failed\n");
            return IOTCS_RESULT_FAIL;
        }
     
        printf("Message is %s\n", device_current_value);
     
        /* free device handle */
        iotcs_free_virtual_device_handle(device_handle);
        /* free device model handle */
        iotcs_free_device_model_handle(device_model_handle);
     
        /*
         * Calling finalization of the library ensures communications channels are closed,
         * previously allocated temporary resources are released.
         */
        iotcs_finalize();
        printf("OK\n");
        return EXIT_SUCCESS;
    }
  2. Compile the c program you created in the previous step.

    gcc -g -I../include -I../lib/arm -o ./hello_world_sample.out ./hello_world_sample.c -Wl,-Bstatic -L../lib/arm -ldeviceclient -Wl,-Bdynamic -lssl -lcrypto -lm -lrt -lpthread 
  3. Verify that your program was successfully compiled by checking that the directory where your C program resides also contains the file hello_world_sample.out
  4. Copy the AAAAAAQB7RGA-B4-provisioning-file.conf that was downloaded when you registered the device into that directory.
  5. To send your first message, run the following command:

    Note: File_Protection_Password is the same you used in the Oracle IoT Cloud Service to download the AAAAAAQB7RGA-B4-provisioning-file.conf file).

    ./hello_world_sample.out AAAAAAQB7RGA-B4-provisioning-file.conf File_Protection_Password
  6. In the Oracle IoT Cloud Service, navigate to your application, then select Data and Explorations, and then select Messages.
  7. Find your message in the Messages table and verify that the message content contains the update to the message attribute to the value "Hello World!".

    Messages board
    Description of this image

Troubleshooting for Activating Devices and Sending Messages

Error: HTTP 400

Possible Causes:

  • The server does not recognize the device ID you provided.
  • The shared secret that you provided for the device is not correct.

Solution:

  • Verify that the device ID and shared secret that you used to create the trusted assets store are the same that appear in the Oracle IoT Cloud Service console.
  • Verify that you are using the right Oracle IoT Cloud Service. If you aren't, generate the asset store again using the correct URL.
Error: wrong name.iot.us.oraclecloud.com

Cause: Unable to resolve the specified name for your Oracle IoT Cloud Service.

Solution: Verify the name and spelling of the URL for your Oracle IoT Cloud Service. Then delete your trusted assets store and create it again using the correct name.

Error: Connection refused

Cause: The specified server URL is not an Oracle IoT Cloud Service.

Solution: Verify the name and spelling of the URL for your Oracle IoT Cloud Service. Then delete your trusted assets store and create it again using the correct name.

Error: connect timed out

Cause: Unable to establish a network connection with specified server URL.

Solution:

  • Check the name and spelling of your Oracle IoT Cloud Service. If it's not correct, then delete your trusted assets store and create it again using the correct name.
  • Verify network connectivity. Also check that that any firewalls or proxy servers between the client device and the Oracle IoT Cloud Service allow HTTPS traffic from the device to the Oracle IoT Cloud Service URL.

Error: no such attribute 'message'

Cause: The specified device model does not have the specified attribute.

Solution:

  • Verify that the URN for the device model you created matches the URN that you used when activating the device in the C POSIX application.
  • Verify that the attribute name and spelling that you chose for your device model match the name of the attribute you are setting in the C POSIX application.

Want to Learn More?