Build Instructions - Mark-Millard/oktopus GitHub Wiki

User Services Platform (USP) - Oktopus

This document contains information on how to configure Ubuntu 22.04 LTS 64-bit linux for the open source Oktopus Controller USP service.

Docker Installation

Docker is used to build multiple USP components for various open source projects.

Use the instructions found on the Get Docker CE for Ubuntu web page to install Docker. Use the "Install using the repository" instructions.

Also, use the instructions on Post-installation steps for Linux to manage docker as a non-root user.

Oktopus USP Controller

Oktopus is a TR-369 Controller. This open source is located on Github at OktopUSP/oktopus.

Oktopus Quick Start

To get started quickly, do the following:

git clone [email protected]:Mark-Millard/oktopus.git
cd oktopus/deploy/compose
COMPOSE_PROFILES=nats,controller,cwmp,mqtt,stomp,ws,adapter,frontend docker compose up -d

This will build and start 15 docker images and one docker network.

  • Network compose_usp_network
  • Container nats
  • Container mongo_usp
  • Container frontend
  • Container file-server
  • Container socketio
  • Container nginx
  • Container stomp
  • Container mqtt
  • Container websockets
  • Container acs
  • Container ws-adapter
  • Container mqtt-adapter
  • Container controller
  • Container adapter
  • Container stomp-adapter
$ docker image ls -a
REPOSITORY               TAG       IMAGE ID       CREATED         SIZE
nats                     latest    30790e9a65a1   3 weeks ago     15.3MB
mongo                    latest    f08e39122805   4 weeks ago     855MB
nginx                    latest    f876bfc1cc63   6 weeks ago     192MB
oktopusp/stomp           latest    89d3cadc93c8   2 months ago    9.26MB
oktopusp/stomp-adapter   latest    e1785ebf535d   2 months ago    14.4MB
oktopusp/mqtt            latest    6d251253ecbb   2 months ago    16.9MB
oktopusp/mqtt-adapter    latest    8e6fde9bb921   2 months ago    15.1MB
oktopusp/ws              latest    89d2351dc38c   2 months ago    17.7MB
oktopusp/ws-adapter      latest    2fe53f616bf1   2 months ago    17.2MB
oktopusp/adapter         latest    929bec684469   2 months ago    22.2MB
oktopusp/file-server     latest    556f0eaf1e93   2 months ago    13.1MB
oktopusp/socketio        latest    7e121325d16c   2 months ago    129MB
oktopusp/acs             latest    ff225b729d79   2 months ago    15.9MB
oktopusp/controller      latest    0bedabefff69   2 months ago    23.3MB
oktopusp/frontend        latest    aeffed1996e4   2 months ago    1.11GB

Oktopus GUI

To use the Gui, simply type "localhost:80" in a web browser. The first time it runs you will need to register as an Administrator User.

GUI Credentials

User: [email protected]
Password: msm@OKTO#100

Stopping USP Controller

To stop the Docker containers, use

$ cd oktopus/deploy/compose
$ ./stop.sh

Running USP Controller

To run the Docker containers, use

$ cd oktopus/deploy/compose
$ ./run.sh

USP Agent

The agent is a piece of software that runs on the CPE or IoT device and is responsable for connecting it to the Controller (Oktopus) through USP. To simulate the behavior of a real device we can use OBUSPA encapsulated in a docker container for better portability.

OBUSPA based agent simulator utility packaged by Oktopus depends on initial configuration files available at /agent folder.

MQTT Message Transfer Protocol (MTP)

To execute the USP Agent with MQTT MTP, do the following:

$ cd oktopus
$ docker run -d -v $(pwd)/agent/oktopus-mqtt-obuspa.txt:/obuspa/oktopus-mqtt-obuspa.txt --network host --name obuspa-mqtt oktopusp/obuspa:latest obuspa -r /obuspa/oktopus-mqtt-obuspa.txt -p -v4 -i lo

This will create the Docker image, oktopusp/obuspa:latest, and run the agent within the container using the command obuspa -r /obuspa/oktopus-mqtt-obuspa.txt -p -v4 -i lo. The Oktopus Controller GUI should show the agent simulator as a registered device using the MQTT MTP.

Websockets Message Transfer Protocol (MTP)

To execute the USP Agent with Websockets MTP, do the following:

$ cd oktopus
$ docker run -d -v $(pwd)/agent/oktopus-websockets-obuspa.txt:/obuspa/oktopus-websockets-obuspa.txt --network host --name obuspa-websockets oktopusp/obuspa:latest obuspa -r /obuspa/oktopus-websockets-obuspa.txt -p -v4 -i lo

This will create the Docker image, oktopusp/obuspa:latest, and run the agent within the container using the command obuspa -r /obuspa/oktopus-websockets-obuspa.txt -p -v4 -i lo. The Oktopus Controller GUI should show the agent simulator as a registered device using the Websockets MTP.

STOMP Message Transfer Protocol (MTP)

To execute the USP Agent with STOMP MTP, do the following:

$ cd oktopus
$ docker run -d -v $(pwd)/agent/oktopus-stomp-obuspa.txt:/obuspa/oktopus-stomp-obuspa.txt --network host --name obuspa-stomp oktopusp/obuspa:latest obuspa -r /obuspa/oktopus-stomp-obuspa.txt -p -v4 -i lo

This will create the Docker image, oktopusp/obuspa:latest, and run the agent within the container using the command obuspa -r /obuspa/oktopus-stomp-obuspa.txt -p -v4 -i lo. The Oktopus Controller GUI should show the agent simulator as a registered device using the STOMP MTP.

Stopping USP Agent

To stop the agent, use

$ docker stop <container_id>

Where <container_id> is the Docker container id for the running USP agent.

[!Warning] It appears that the Oktopus obuspa agent does not go "Offline" in the Oktopus Controller GUI when the container is stopped. This is probably a bug since the agent is no longer sending a heartbeat.

Resources