Home

The CPSwarm Deployment Tool is a lightweight software update and monitoring system for resource-constrained IoT devices. It aims to provide secure, practical, and easy to use utilities for over-the-air (OTA) provisioning of software on small computers (e.g. Raspberry Pi or other device with ARM/x86 architecture). The project is under active development and not ready for production.

Contents

1. Components
2. Terminology
3. API
4. Example

Components

The Deployment Tool consists of two components:

• Deployment Manager: a centralized web service exposing APIs for various deployment-related operations.
• Deployment Agent: a web service running on individual devices, performing deployment-related commands received from the Deployment Manager.

Terminology

Target

Target is a device that hosts a running instance of the Deployment Agent. Each Target has a unique ID and a set of tags (e.g. device type, group) which identify the device. The ID is set as part of Deployment Agent configuration. The tags can be configured similarly to the ID or remotely via the Deployment Manager API.

Order

Order is a set of instructions and configurations for an intended deployment process. This process includes typical deployment steps such as assembly, transfer, installation, testing, and activation. In addition, the Order provides information about target devices and logging requirements.

API

The API is documented using the OpenAPI specification and is available on Swagger Hub.

Example

In this example. We submit a deployment order and validate the results using runtime logs.

The Order is submitted to the Deployment Manager via the RESTful API of the service. The API supports both YAML and JSON representations during the submission but all responses are in JSON.

In the example below, a package is available locally in a directory named package and transferred to devices with tags turtlebot and dev. Once the transfer is complete, the package is installed. After the successful install, the applications are executed as subprocesses. The Deployment Agent collects the logs locally and sends state information to the Manager. In this example, since the debug flag is set to true, both process logs and state information are sent to the Manager. If the debug flag was unset, the logs would only be sent on requests using the API.

source:
  paths:
    - package

deploy:
  # How to install the package(s)
  install:
    commands:
      - go build count_to_three.go
  # How to launch the application(s)
  launch:
    commands:
      - ./count_to_three
   
  # Which target devices should receive the package
  target:
    ids:
    tags:
      - turtlebot
      - dev

# Whether the device should send all standard output (true) or just status info
debug: true

In response, the API provides the submitted order along with a system generated ID (in this case ddaae585-f841-4d8c-9e82-0cfe9cac664e) and information about matching targets.

Following an Order submission, the Deployment Manager creates a package consisting all necessary information for performing the deployment on a target. This usually includes the compressed package data, installation steps, and execution commands.

Target Registry

The Deployment Manager maintains the list of Targets. The list is populated when Deployment Agents advertise their presence. The Deployment Manager provides a RESTful API for managing the Targets.

Below is the Target Registry index after deployment of the above task. The example registry consists of one target with three tags. Since the dev tag from the Order matches this target, the target has received the order and provided the status and output logs.

{
  "my-laptop": {
    "tags": [
      "dev",
      "macOS",
      "test"
    ],
    "logs": {
      "ddaae585-f841-4d8c-9e82-0cfe9cac664e": {
        "transfer": {
          "SYS": [
            {
              "output": "STAGE-START",
              "time": 1544106477311587000
            },
            {
              "output": "subscribed to task",
              "time": 1544106477311675000
            },
            {
              "output": "received task",
              "time": 1544106478314774000
            },
            {
              "output": "STAGE-END",
              "time": 1544106478318157000
            }
          ]
        },
        "install": {
          "SYS": [
            {
              "output": "STAGE-START",
              "time": 1544106478318182000
            },
            {
              "output": "STAGE-END",
              "time": 1544106479781004000
            }
          ],
          "go build count_to_three.go": [
            {
              "output": "EXEC-START",
              "time": 1544106478318376000
            },
            {
              "output": "EXEC-END",
              "time": 1544106479780976000
            }
          ]
        },
        "run": {
          "./count_to_three": [
            {
              "output": "EXEC-START",
              "time": 1544106479783301000
            },
            {
              "output": "hello 1",
              "time": 1544106479794130000
            },
            {
              "output": "hello 2",
              "time": 1544106480795342000
            },
            {
              "output": "hello 3",
              "time": 1544106481796647000
            },
            {
              "output": "EXEC-END",
              "time": 1544106482797779000
            }
          ],
          "SYS": [
            {
              "output": "STAGE-START",
              "time": 1544106479783228000
            },
            {
              "output": "STAGE-END",
              "time": 1544106482797874000
            }
          ]
        },
        "updated": 1544106485902352000
      }
    },
    "lastLogRequest": 1544096015201259000
  }
}