Table of contents

Motivation

For an overview of the motivation behind scaffold see this position paper.

Installation

Prerequisites

To install, clone the three repositories, scaffold-base, scale and scanner, and run cabal install in the main folder in that order.

Development lifecycle overview

Firstly, the Scaffold backend must be hosted and running in the network where we desire to use it. To do this, just run scnd on any machine in the network. (mDNS-SD usually doesn’t work with 802.1X without specific configuration).

The next step is to configure all of the Scaffold nodes. They need to be running the scaffold runtime, which will ensure that they advertise their services to the registry backend. They need to be appropriately configured as described in configuration. Moreover, these nodes need to be able to be accessed via an ssh user with password “scaffold”.

Then, the network-wide application code should be defined using the Scale programming language. This code can then be compiled with the scale compiler scc. This will generate a set of Haskell programs and application requirements.

We can then use the information present in the registry to deploy the application. This is done using the command scn deploy. The registry should be discovered automatically through mDNS-SD, but if that doesn’t happen it can be specified manually with the -r flag.

After this the application should be deployed and running. For end-to-end examples see Examples.

Scaffold Node Setup

These instructions will show how to install the runtime on a target IoT node and make sure that a node is suitable to be used as part of a Scaffold network. For the time being we only support Edison with Ubilinux, but the instructions might be appropriate for other nodes running Linux.

Dependencies

After installing all the dependencies, copy the Scaffold source folder from scaffold-base/src and the Scale source folder from scale/src to the home directory of the user that will be used to install Scaffold applications. Optionally install the scaffold runtime to start at boot. The mosquitto daemon must be enabled when using the node.

The node should be able to be accessed by the user specified in the registration by ssh with no password or the password “scaffold”, and the home directory must be writable. If using the runtime, the folders /etc/scaffold.d/sensors and /etc/scaffold.d/actuators must be both created and populated according to the instructions on section configuration. Otherwise, just make sure that the driver script specified in scn register (see Scanner Registry Guide) is executable by the user specified.

Configuration files

The configuration files for sensors and actuators have a similar format. For sensors:

sensor {
  query="<query>"
  driver="<driver>"
  user="<user>"
}

For actuators:

actuator {
  command="<command-descriptor>"
  driver="<driver>"
  user="<user>"
}

They should be placed in /etc/scaffold.d/sensors and /etc/scaffold.d/actuators, respectively. These files specify the capabilities of the nodes. <query>/<command-descriptor> will be the tags with which they can be referenced within Scale. The <driver> parameter corresponds to a shell command which should read the sensor and print the result to stdout in the case of a sensor, or execute the actuator described by <command-descriptor>, in the case of an actuator. <user> is the ssh user that will be used to execute this command. The password for this user should be “scaffold”, or ssh keys should be appropriately set up. Obviously this negates all of the security properties provided by SSH, so make sure to appropriately restrict the capabilities of the scaffold user and control access to the node address if necessary. Security will be addressed in a future version of Scaffold.

Scaffold Runtime Guide

When compiling scaffold-base, the scaffold executable will be produced. This is a SysV init style daemon, and can be copied to /etc/init.d and symlinked into /etc/rc.d as usual. Support for systemd and upstart is coming soon.

If you don’t require dynamic advertisement, you can just run scn register to manually register the node with the configuration in /etc/scaffold.d. See Scanner Registry Guide for details on how to use this command.

Scanner Registry Guide

The Scanner backend is run by executing scnd on the host. This will open a server on a port that can be specified in the configuration file in /etc/scaffold.conf, with key port, by default 1234. For instance:

port="4321"

would result in the backend using port 4321. A sqlite database file can be created by in the current working directory by running scn init before executing scnd. An alternative path can be specified in the configuration file, with key dbpath.

The runtime can then be accessed with the scn client. scn will attempt to automatically detect the runtime in the network by using mDNS-SD, but the registry can be manually specified with the -r option to scn. scn supports the following commands:

    Usage: scn register [-r|--registry <host>] [-n|--node <ip>]
                        ([-s|--sense <query>] | [-a|--actuate <actuator>])
                        [-d|--driver <exec>] [-u|--user <username>]

    Available options:
      -h,--help                Show this help text
      -r,--registry <host>     Registry to use, defaults to core.
      -n,--node<ip>           Node IP to register
      -s,--sense <query>       Sensing capability to register
      -a,--actuate <actuator>  Actuation capability to register
      -d,--driver <exec>       Driver to use
      -u,--user <username>     Username to use

Allows us to register a node capability in the registry, along with sensing or actuation capabilities. CPU and memory will be detected on supported operating systems. Moreover, if registering the current machine by omitting the host argument, it will read the configuration files in /etc/scaffold.d and read sensor/actuator description files. If more than one sensing/actuation capability is to be manually registered, the command should be run several times.

q := Provides d | IsCapableOf c | Fulfills r | And q q | Any
sshport="2222"

Scale Programming Language Guide

Scale is the programming language used to specify the network-wide application behaviour. The theory behind Scale is paradigm agnostic, but in this release we only have one instantiation of Scale, for a Haskell-like language. The key concept of Scaffold is to abstract away from individual nodes by using descriptions of the data they provide, the commands they can perform, or the processing capabilities they offer. These are represented as data queries, d, commands, c, and requirements, r.

Then, a Scale program is a Haskell program with the addition of certain constructs:

These constructs will guide the way in which the program gets distributed throughout the network. See Examples for examples of how this might happen.