Get access to the new Intel® IoT Developer Kit, a complete hardware and software solution that allows developers to create exciting new solutions with the Intel® Galileo and Intel® Edison boards. Visit the Intel® Developer Zone for IoT.
IoT Analytics: Login and Account Creation
To begin using the IoT Analytics cloud site, create a new administrative user account that will have the ability to register devices, manage alerts, create accounts, and perform other tasks on the site.
Go to the IoT Analytics Dashboard website. Figure 1 shows the Sign in screen that will be displayed.
Figure 2. Creating an Account on the IoT Analytics site
You have the option of using your Facebook, Google+, or GitHub authentication, or you can create a local account with an email address and password. If you click Sign Up Here, the Create user page appears (see Figure 2).
Figure 3. Create a New User
The Create user screen requires a valid email address (used to send the activation link to complete account creation) and a user-provided password. Review the Terms and Conditions, and if you agree, select the I agree to the Terms and Conditions of Use check box, and then click Create.
After the user login has been created, you are prompted to create an account name (see Figure 3).
Figure 4. Create a New Account
This name appears on the site when you log in. When you have authenticated, the My Dashboard page appears (see Figure 4).
Figure 5. User Dashboard and Navigation Page
My Dashboard provides access to all system functions, including the number of devices, the number of observations received in the past hour, and the percentage of devices that are "healthy," meaning they have transmitted data recently. You can customize the lower section to show a "favorite" chart, which contains a chart of specific time series from specific devices. This is described more fully in the User Manual.
Account Administration
Each account that you create on the IoT Analytics site is a separate workspace. You administer the accounts from the My Account page (see Figure 5).
Figure 6. Account Administration
From this page, you can view the account details, invite additional users to participate in the analytics site (by registering their email address) and manage the catalog of Component Types.
Component Types are the templates which define time series and actuators to be used by your devices. Note that the catalog already contains a Component Type named "temperature.v1.0" which we will use in the following examples. This defines a time series where each observation is a floating point number, and the unit-of-measures is "Degrees Celsius".
IoT Kit Agent
The IoT Analytics site supports a REST interface, making it possible to write client software which runs on the device and sends observations to the cloud. However, to simplify this process, there is also an Agent. The agent runs as a daemon on the device, listening for simple messages from other processes and handling the necessary message formatting and security to send observations to the cloud. The agent comes with another program, iotkit-admin, which provides many utility functions, such as tesing the network, activating a device, registering time series, and sending test observations.
The next steps depend on whether the iotkit-agent and iotkit-admin program are pre-installed:
Galileo and Edison Device with the Agent pre-installed
If you have a Galileo or Edison, you can see if the iotkit-agent and iotkit-admin are pre-installed by typing the following in the shell:
iotkit-admin
If this results in "Usage: iotkit-admin …", then the program is pre-installed. This means:
- You do not need to install Node.js, npm or the agent code.
- The programs are in the path and you can run them from any directory.
- You do not need to add the ".js" suffix to the program names. For example, you can type "iotkit-admin" rather than "iotkit-admin.js" (without the quotes).
- The agent is controlled by "systemctl", the systemd service manager.
If this is the case, type the following in the shell to stop the agent. We will start it again later.
systemctl stop iotkit-agent
Agent is not pre-installed
Network Test
To test network connectivity, run the following command from the command line:
iotkit-admin test
This command should produce the following message:
2014-11-10T21:50:54.062Z - info: Trying to connect to host ...
2014-11-10T21:50:54.570Z - info: Connected to dashboard.us.enableiot.com
2014-11-10T21:50:54.571Z - info: Environment: prod
2014-11-10T21:50:54.571Z - info: Build: 0.10.6
If you are trying to connect from behind a firewall with a proxy server, add the proxy server to the iotkit-admin configuration:
iotkit-admin proxy http:
Repeat the above test command. If you are still having connection problems, you must correct them before you can proceed with the installation.
Note: This is specific to the REST protocol. MQTT will not operate via a proxy.
Getting and Changing the Device ID
You should know your device ID because you may need it to find the device in the device list if you have more than one device. You can display the device ID with the following command:
iotkit-admin device-id
You can change this device ID (if desired) by running the following command.
Note: Changing the ID does not provide anonymity. Device ID’s should be unique. The source TCP/IP address will still be available to the cloud server.
iotkit-admin set-device-id «device_id»
It is also important to note that the device activation step returns a security token which will only work with the device ID which was used at activation. The device ID should not be changed after activation.
Activating the Device
To complete the device activation, you must supply a specific account activation code from the IoT Analytics account Details page (see Figure 6).
Figure 7. My Account Agent Activation Code
The code is valid for only 60 minutes. After that, you will have to regenerate the code by clicking the button indicated in Figure 6. You must supply this code when activating the device:
iotkit-admin activate «activation_code»
The activation process creates the device record in the cloud, associates the device with the account (where the activation code came from), and provides the device with security credentials.
Figure 8. Accessing the Devices page
The My Devices page will be displayed where you can see the newly activated device. Click the Device ID (as shown in Figure 8) to see the device’s detailed information.
Figure 9. The My Devices Page and the Add New Devices Dialog Box
Sensor Registration and Data Submission
Now that the device has been activated, the next step is to register components. A component is either a time series which consists of sensor observations sent from the device, or an actuator, which allows commands to be sent to a device. For example, if you want to send both temperature and humidity, you would register two components.
Each component you reference for a device must reference a "Component Type" within the account Catalog. Why Component Types? If you had many devices throughout a city that all measured the same thing, such as Nitrogin dioxide (NO2) content, Component Types save you the trouble of defining the details of the time series over and over for each device. Instead, the Catalog would hold a Component Type for Nitrogen dioxide, which would define a time series of integer values, with the unit-of-measure of "NO2 pphm" (parts per hundred million). The unit-of-measure is printed on the Y access whenever the time series is charted.
You access the Catalog from My Account, as shown in Figure 9.
Figure 10. The Component Catalog from the My Account Page
There are three default components in each account: humidity, power, and temperature. You can also add new Component Types from the Add a New Catalog Item dialog box. If a new component type is added, the local agent must be restarted before that type can be used to register a new component.
You perform the registration step only once for each Component (i.e. time series) — for example:
iotkit-admin register temp temperature.v1.0
Here we are registering a time series that references the Component Type named "temperature.v1.0" in the Catalog. Here we have created an alias "temp" which will be used to send temperatures observations to the agent.
You can find the Component Types which have been registered in the Catalog using the following command on the device:
iotkit-admin catalog
Note: Any catalog changes made in the dashboard will not be reflected locally until the agent is restarted or a ‘sync’ command is issued manually.
Now that the component has been registered, it is possible to begin sending observations to the IoT Analytics site for this component. There are several ways to do this, but to test that everything is working, run the observation command to send individual observations to the IoT Analytics site:
iotkit-admin observation temp 35
iotkit-admin observation temp 30
Each of these two commands cause one observation to be sent to the IoT Analytics site. The "temp" alias indicates these observations should be added to the "temp" time series which was previously registered.
Switch back to the website and select Chart from the navigation pane to select the device and component and see the newly sent data elements (Figure 10). Hover over the ends of the lines to see the specific values and the timestamps when the observations were sent.
Figure 11. Chart for the Selected Device and Component
Sending Multiple Data Packets
The "iotkit-admin observation" command is intended to facilitate testing, not for continuous data capture. There are two additional ways to send observation data to the IoT Analytics site:
- A client can use the REST interface documented at https://github.com/enableiot/iotkit-agent/wiki/Api-Home to interacttly directly with the cloud.
- A client can send User Datagram Protocol (UDP) packets to the local Agent. The Agent converts these packets into REST calls and sends the request on behalf of the client.
This section explains how to use the Agent. First, the agent must be running. On the Galileo or Edison with the software pre-installed, you can use the following command:
systemctl start iotkit-agent
If you installed the agent yourself, just open a terminal window, "cd" to the iotkit-agent directory, and run:
./iotkit-agent.js
and leave it running. Open a second terminal to run the following commands.
You can send UDP-formatted messages to the Agent through the device localhost on port 41234 (e.g., UDP://localhost:41234). First, create a JavaScript Object Notation (JSON)–formatted document, where the key "n" is the name of a time series and "v" is the value:
{ "n": "<sensor name>", "v": "<value>" }
Examples:
{ "n": "temp", "v": 21.0 }
{ "n": "humidity", "v": 71.5}
Most programming languages can transmit this message, but on Mac OS X* and Linux*, use the nc program as follows:
echo -n '{"n": "temp", "v": 21.0}' | nc -u -w1 127.0.0.1 41234
This command sends the document to the agent. The agent (which is listening on port 41234 for the UDP messages) will convert the observation to a REST web service call (or MQTT messages) and forward it to the IoT Analytics site.
Windows does not include the "nc" command, and the –u argument is not supported on the Yocto build used on the Galileo and Edison boards. For this reason we have included a utility with the Agent that you can use to do the same thing.
send-udp.js temp 21.0
This simple program will create the JSON document and send it to port 41234 on localhost using UDP. If you cannot find the program, run the following command to get the latest release of the iotkit-agent, and try it again.
npm update iotkit-agent
