Quick Start Guide for Containerized IoTivity-Lite Resources
Introduction
This guide provides a brief introduction to the use of container images that provide various examples of applications built with IoTivity-Lite. These images include:
- The
ocfadmin/iotivity-examples
image - a collection of basic IoTivity-Lite applications that can be used to quickly show how OCF Devices built with IoTivity-Lite interact with each other. - The
ocfadmin/iotivity-builder
image - a portable development environment that can be used to compile and run IoTivity’s example applications and more. - The
ocfadmin/devicebuilder
image - a containerized version of OCF’s DeviceBuilder, which can be used to generate source code scaffolding for IoTtivity-Lite.
These images are available on DockerHub, and their source code/image definitions are available on GitHub.
Note that these containers are prototypes for demonstration purposes.
Prerequisites
The remainder of this guide assumes the use of Docker
and docker-compose
. The images described
in this guide are Linux-based, but their primary functionalities should be
consistent on any platform that can run Docker.
You should be familiar with basic docker
and docker-compose
commands. But no
special configuration of the Docker runtime should be required unless explicitly
stated. More advanced examples may utilize volumes and/or bind mounts.
Example IoTivity-Lite Applications
Quick Start with docker-compose
The fastest way to try out an example OCF domain where example Devices built
with IoTivity-Lite can be discovered, onboarded, and configured to interoperate
is with the ocfadmin/iotivity-examples
examples image.
Starting the Example
The following docker-compose
file can be used to quickly spin up a full
example:
# docker-compose.yml
version: '3.8'
services:
obt:
container_name: obt
image: ocfadmin/iotivity-examples
tty: true
stdin_open: true
command: onboarding_tool
networks:
- ocfnet
simpleserver:
container_name: simpleserver
image: ocfadmin/iotivity-examples
tty: true
stdin_open: true
command: simpleserver
networks:
- ocfnet
simpleclient:
container_name: simpleclient
image: ocfadmin/iotivity-examples
tty: true
stdin_open: true
command: simpleclient
networks:
- ocfnet
# Note that IPv6 is not officially supported in compose file v3....
# IPv6 support must be enabled in /etc/docker/daemon.json
networks:
ocfnet:
enable_ipv6: true
ipam:
driver: default
config:
- subnet: 172.16.2.0/24
gateway: 172.16.2.1
- subnet: 2001:db8:2::/64
gateway: 2001:db8:2::1
This file can also be downloaded from GitHub.
This file defines instances of the three example IoTivity-Lite applications that
the examples image comes with - simpleserver
, simpleclient
, and
onboarding_tool
. These each represent OCF Devices, and can interact together.
simpleserver
acts as a lamp and simpleclient
controls the lamp.
This example can be run with the following commands, assuming that the compose
file (docker-compose.yml
) is present in the current working directory. Note
that, if you haven’t yet pulled the ocfadmin/iotivity-examples
image, that
docker-compose
will pull it for you.
# Use the docker-compose file to spin up application instances
docker-compose up -d
# In one terminal, follow logs for the simpleserver and simpleclient containers
docker-compose logs -f simpleserver simpleclient
# In another temrinal, attach to onboarding_tool container
docker attach obt
# Output will be blank; enter 0 and hit return to cause OBT to display menu
At this point, you should see some minimal output from the simpleserver
and
simpleclient
logs, and the OBT’s main menu should appear on screen. An example
of what this might look like appears below.
From here, the OBT can be used to discover, onboard, and configure the
simpleserver
and simpleclient
Devices.
Onboarding Devices
For our example, we will first onboard simpleserver
(the lamp) using the
Random PIN Ownership Transfer Method. We will then onboard simpleclient
(the
light controller/”phone”) with the Just-Works Ownership Transfer Method.
This can be done by following these steps (entered into the OBT):
Onboarding Lamp Device (Random PIN)
- Discover the unowned devices by entering “1”. Two devices (and their network addresses) should appear in the OBT’s output.
- Enter “9” to “Request Random PIN from device for OTM”. Then enter the appropriate number to select the “Lamp” Device.
- In the output for the Devices, a Random PIN should appear. Enter “10” in the OBT to perform “Random PIN Ownership Transfer Method”. Once again enter the appropriate number to select the “Lamp” Device.
- When prompted, enter the PIN that was displayed in the
simpleserver
’s log output and hit return. - If the pin was entered correctly, the OBT should report that it has “Successfully performed OTM” on the Lamp Device.
Onboarding Controller/Phone Device (Just-Works)
- Enter “8” to perform “Just-Works Ownership Transfer Method”.
- Enter the appropriate number to select the Device labeled “Kishen’s IPhone”.
- The OBT should indicate that it has “Successfully performed OTM”.
Verify Ownership Status
At this point, both Devices should have been onboarded by the OBT. To verify this, enter “4” into the OBT; both Devices should appear in the output as owned Devices.
Provisioning Devices
With both Devices onboarded, we can now use the OBT to provision credentials and access control lists (ACLs/ACEs) to allow them to interoperate with each other.
The following steps can be used to perform this provisioning:
- Enter “12” into the OBT to “Provision pairwise credentials”.
- Choose either Device as “device 1”, then the other Device as “device 2”.
- Next, Enter “13” to “Provision ACE2”.
- Select the Lamp.
- Select “Kishen’s IPhone” as the Subject.
- Enter “1” for the “number of resources in this ACE”.
- Enter “1” (for Yes) for “Have resource href?”
- Enter “/a/light” for the “resource href”.
- Enter “1” (for Yes) to ACE2 Permissions for RETRIEVE, UPDATE, and NOTIFY (you may also simply enter “1” for all 5 permissions).
The screenshot below illustrates what setting the 5 ACE permissions might look like.
Device Interoperation
At this point, the simpleserver
and simpleclient
Devices should have
everything they need to interoperate with each other. To demonstrate the Devices
interacting with each other, we will need to restart the simpleclient
Device.
Enter “99” to exit the OBT, and ensure that your other terminal is still
following the logs from docker-compose
(docker-compose logs -f simpleserver
simpleclient
).
Use docker restart simpleclient
to restart the simpleclient
Device. Observe
the logs in your other terminal to see that the phone/controller Device is able
to update the state of the Lamp Device and observe its state changes!
The image below displays what this output might look like.
Running Manually
The ocfadmin/iotivity-examples
image can also be instantiated individually.
Each of the applications that come with the image can be started with the
following commands. Each invocation specifies the -i
and -t
flags to ensure
that output (and input, in the case of the OBT) is properly captured.
# Start simpleserver
docker run --name=simpleserver -i -t ocfadmin/iotivity-examples simpleserver
# Start simpleclient
docker run --name=simpleclient -i -t ocfadmin/iotivity-examples simpleclient
# Start onboarding tool (must specify -i and -t to properly attach to input)
docker run --name=obt -i -t ocfadmin/iotivity-examples onboarding_tool
DeviceBuilder Image
The OCF DeviceBuilder tool can be
used to generate stubs of IoTivity-Lite application code. The
ocfadmin/devicebuilder
image enables the use of this tool without the need to
install and configure it. Refer to the DeviceBuilder documentation for details
on how DeviceBuilder can be used.
The DeviceBuilder image is generally used with the following command:
docker run --rm -v <path to input file directory>:/devbuilder input.json <device type>
This image requires the use of either volumes or bind mounts, to allow the container process to access the input JSON file.
Generated code is produced in a directory named output
, which is created in a
location relative to the volume or bind mount.
Example Use
In this example, assume that the following JSON file is located in the current
working directory and named speaker_model.json
:
[
{
"path": "/speaker",
"rt": [ "oic.r.switch.binary", "oic.r.audio" ],
"if": [ "oic.if.a", "oic.if.baseline" ]
}
]
The DeviceBuilder image can be used to generate IoTivity-Lite application code with the following command:
docker run --rm -v "$(pwd)":/devbuilder ocfadmin/devicebuilder speaker_model.json oic.d.speaker speaker-server
This command specifies the following:
- The current working directory is bind-mounted to
/devbuilder
in the container process. - The input JSON file is specified (
speaker_model.json
).- Note that this file is relative to the
/devbuilder
directory in the container.
- Note that this file is relative to the
- The device type identifier
oic.d.speaker
. - The name/title of the device, “speaker-server”.
- Note that this argument is optional.
The result of running this command is a new directory named output
being
created in the working directory. This directory includes generated source code
that can be compiled with IoTivity-Lite, as well as schema files. An example of
the structure of this output directory appears below.
IoTivity-Builder Image
The ocfadmin/iotivity-builder
image can be used to compile IoTivity-Lite
applications. It includes the entire IoTivity-Lite code base, and can be used
with bind mounts or volumes to compile new code (such as that generated by
DeviceBuilder).
This guide will demonstrate how to use the image to create a simple development environment shell that can be used to compile and run the existing IoTivity-Lite example applications. For more advanced examples for the use of the image, refer to the documentation and guides on GitHub.
To execute an interactive shell from which IoTivity-Lite applications can be complied, use the following command:
docker run --name=iot-dev -i -t --entrypoint=/bin/bash ocfadmin/iotivity-builder
This will open a shell in the container’s working directory of
/iotivity-lite/port/linux
, inside which the default example applications that
come with IoTivity-Lite can be compiled and run.
For example, the following commands (run inside the container) can be used to
build the simpleserver
example application with debug logging enabled:
make cleanall
make DEBUG=1 simpleserver
Once the applications have been compiled, their executables can be run directly within the container:
./simpleserver