Tools
The Calvin tools consists of the following commands
csdocs: Show documentationcsruntime: Start and stop runtimescscontrol: Control runtimes (including deploying applications)csviz: Visualize an application as a flow-graphcsmanage: Manage the host's actor store and credentialscsweb: Start web server with a Calvin-debuggercscompile: Compile a CalvinScript file into a deployable representation
explained below.
The command csdocs will show documentation about actors and components. Used with arguments
it will show all the top level namespaces available.
$ csdocs
Calvin
A systematic approach to handling impedance mismatch in IoT.
Modules: chart, exception, flow, io, json, math, media, misc, net, per, sensor, std, test, text, time, web
The default behviour is to produce a terse output, so adding the flag --format detailed is generally a good idea when starting out:
$ csdocs --format detailed
============================================================
Module: Calvin
============================================================
A systematic approach to handling impedance mismatch in IoT.
Modules:
chart : Actors related to charts
exception : This module provides actors related to exception handling.
flow : This module provides actors related to handling of data flow.
io : This module organizes actors related to input and output.
...
By giving a namespace as an argument, the documentation for the corresponding module is shown:
$ csdocs --format detailed flow
============================================================
Module: flow
============================================================
This module provides actors related to handling of data flow.
Actors:
Alternate : Fetch tokens from the fan-in port in the order given by the argument 'order'
Collect : Collect tokens from many ports on the inport
CollectDict : Collect tokens from token port, forming a dict according to mapping. May produce
Dealternate : Route tokens to the ports connected to the fan-out port token in the order given by the argument 'order'
Init : Insert an initial token (data) before passing all others through
...
Finally, giving the fully qualified name of an actor as argument, we get the documentation for that actor:
$ csdocs --format detailed flow.Init
============================================================
Actor: flow.Init(data)
============================================================
Insert an initial token (data) before passing all others through
Inports:
in : Any token
Outports:
out : Data given as parameter followed by data from in port
usage: csdocs [-h] [--all] [--format {detailed,compact,raw}]
[--prettyprinter {plain,md}]
[<actor or module>]
Provide documentation for modules, actors, and components.
positional arguments:
<actor or module> What to look up documentation for, if empty show top
level documentation
optional arguments:
-h, --help show this help message and exit
--all Generate complete actor documentation in Markdown
format
--format {detailed,compact,raw}
Options "detailed" and "compact" returns pretty-
printed text, while "raw" returns a JSON-formatted
representation that can be used to generated the
documentation in other formats.
--prettyprinter {plain,md}
When "--format detailed" is in use, this options
allows a choice between plain text and markdown
(calvin)[11:45:59] eperspe sensor-kit$
This command is used to start runtimes
csruntime --host <address> --port <port> --controlport <controlport>
where port and controlport defaults to 5000 and 5001, respectively. So it is possible to start a runtime locally using
csruntime --host 127.0.0.1
When a runtime is started, it can communicate via two uris: The control uri which is used to send commands to a runtime using a REST-interface, and has the form http://<address>:<controlport> and an internal runtime uri calvinip://<address>:<port> which is used for runtime to runtime communication.
Optionally and with the possibility to setup up listeners on multiple interfaces for runtime to runtime communication, uris can be specified with the argument -uri. A uri is specified in the form <schema>://<address>:<port>, supported schemas and interfaces are calvinip for TCP/IP and calvinbt for Bluetooth RFCOMM. Example:
csruntime --uri calvinip://<address>:<port> --uri calvinbt://<bluetoothid>:<port>
Note that invoking
$ csruntime --host localhost <scriptfile>
with a CalvinScript file as argument will start a runtime, invoke the compiler for you, and then
deploy the resulting application. By default, the program will exit after 3 seconds unless another timeout is given using the --wait <timeout> option.
This is not the recommended way of deploying applications, only intended for one-shots during development. See cscontrol for how to deploy applications in the general case.
usage: csruntime [-h] [--name <name>] [-n <host>] [-p <port>] [-c <port>]
[-u URIS] [-d] [-l LOGLEVEL] [-f LOGFILE] [-w sec]
[-x <calvinip>] [-y <url>] [--keep-alive] [--attr <attr>]
[--attr-file <attr>]
[--dht-network-filter DHT_NETWORK_FILTER] [-s]
[--credentials <credentials>] [--uuid <uuid>]
[<filename>]
Start runtime, compile calvinscript and deploy application.
positional arguments:
<filename> source file to compile
optional arguments:
-h, --help show this help message and exit
--name <name> shortcut for attribute indexed_public/node_name/name
-n <host>, --host <host>
ip address/hostname of calvin runtime
-p <port>, --port <port>
port# of calvin runtime
-c <port>, --controlport <port>
port# of control interface
-u URIS, --uri URIS URI of calvin runtime 'calvinbt://id:port'
-d, --debug Start PDB
-l LOGLEVEL, --loglevel LOGLEVEL
Set log level, levels: CRITICAL, ERROR, WARNING, INFO,
DEBUG and ANALYZE. To enable on specific modules use
'module:level'
-f LOGFILE, --logfile LOGFILE
Set logging to file, specify filename
-w sec, --wait sec wait for sec seconds before quitting (0 means
forever).
-x <calvinip>, --external <calvinip>
exposed external calvin ip (e.g. outside of container)
-y <url>, --external-control <url>
exposed external control url (e.g. outside of
container)
--keep-alive run forever (equivalent to -w 0 option).
--attr <attr> JSON coded attributes for started node e.g.
'{"indexed_public": {"owner": {"personOrGroup":
"Me"}}}', see documentation
--attr-file <attr> File with JSON coded attributes for started node e.g.
'{"indexed_public": {"owner": {"personOrGroup":
"Me"}}}', see documentation
--dht-network-filter DHT_NETWORK_FILTER
Any string for filtering your dht clients, use same
for all nodes in the network.
-s, --storage-only Start storage only runtime
--credentials <credentials>
Supply credentials to run program under e.g.
'{"user":"ex_user", "password":"passwd"}'
--uuid <uuid> Set the UUID of the runtime. Does not apply when
security is enabled.
This is a generic command to send control commands and queries to runtimes, but the most common use of cscontrol is deploying applications.
To compile and deploy an application use the form
cscontrol http://<address>:<controlport> deploy <calvinscript file>
e.g.
cscontrol http://127.0.0.1:5001 deploy myscript.calvin
For an overview of the API, see the Calvin Control API page, or point a browser to a runtime, e.g.:
firefox http://127.0.0.1:5001
usage: cscontrol [-h] [--credentials <credentials>]
[--security_dir <security_dir>]
<control uri> {id,nodes,deploy,actor,applications,storage}
...
Send control commands to calvin runtime
positional arguments:
<control uri> control uri of node
{id,nodes,deploy,actor,applications,storage}
id get id of node
nodes handle node peers
deploy deploy script to node
actor handle actors on node
applications handle applications deployed on node
storage handle storage
optional arguments:
-h, --help show this help message and exit
--credentials <credentials>
Supply credentials to run program under e.g.
'{"user":"ex_user", "password":"passwd"}'
--security_dir <security_dir>
Path to the runtimes credentials dir if not using the
default location
This tool allows you to visualize an application as a data flow graph.
usage: csviz [-h] --script SCRIPT [--deployment | --component COMPONENT]
Generate a DOT output for use with GraphViz to generate a vizualization
of the Calvin application graph.
Typical usage would be something like (Linux):
csviz --script foo.calvin | dot -Tpdf | pdfviewer -
or (Mac OS X):
csviz --script foo.calvin | dot -Tpdf | open -f -a Preview
optional arguments:
-h, --help show this help message and exit
--script SCRIPT script file to visualize.
--deployment expand all components into constituent parts.
--component COMPONENT
show internals of a component in script.
Manage the host's actor store and credentials, where the most common use is to install actors and components.
When writing applications, some of the component declarations might be of general use, and therefor it is possible (even recommended) to install them into an actor store for reuse. An installed component will look and behave as an actor, having the same semantics of inports, outports and arguments.
Installing a component from a script is as easy as:
csmanage install component --namespace <ns> --script <calvinscript file> --component <comp name>
Full usage description for csmanage install component:
$ csmanage install component -h
usage: csmanage install component [-h] [--force] [--org <name>] --namespace
<ns.sub-ns> --script <path>
(--all | --component <component> [<component> ...])
optional arguments:
-h, --help show this help message and exit
--force overwrite components or actor that exists at
destination
--org <name> Code Signer org name used, assumes default location
when no calvin.conf
--namespace <ns.sub-ns>
namespace to install actor or components under
--script <path> script file with component definitions
--all install all components found in script
--component <component> [<component> ...]
name of component(s) to install
If you have written an actor, install it using
csmanage install actor --namespace <ns> --path <source file>
Full usage description for csmanage install actor:
$ csmanage install actor -h
usage: csmanage install actor [-h] [--force] [--org <name>] --namespace
<ns.sub-ns> --path <path> [<path> ...]
optional arguments:
-h, --help show this help message and exit
--force overwrite components or actor that exists at
destination
--org <name> Code Signer org name used, assumes default location
when no calvin.conf
--namespace <ns.sub-ns>
namespace to install actor or components under
--path <path> [<path> ...]
actor file (or files) to install
usage: csmanage [-h] {install,cs,ca,runtime} ...
Manage the host's actor store and credentials
positional arguments:
{install,cs,ca,runtime}
command help
install install components and actors
cs manage CS
ca manage CA
runtime manage runtime certificates and keys
optional arguments:
-h, --help show this help message and exit
This command starts a webserver, serving a Calvin debugging tool.
csweb --port 8000 &
firefox http://localhost:8000
usage: csweb [-h] [-p <port>] [-a <address>]
Start web server with a Calvin-debugger.
optional arguments:
-h, --help show this help message and exit
-p <port>, --port <port>
port# of tcp server
-a <address>, --address <address>
address of tcp server
The compiler, cscompile will compile a CalvinScript source file into a
JSON representation. By default, the output will be written to a file with the
same name as the input file, but with the extension replaced by 'json' instead
of whatever extension the input file had (if any).
In general, the compiler is not invoked directly.
For up-to-date information, run it with an -h argument.
usage: cscompile [-h] [--compact] [--sorted] [--issue-fmt FMT] [--verbose]
[--deployscript | --intermediate]
[--stdout | --output <filename>]
<filename> [<filename> ...]
Compile a CalvinScript source file, <filename> into a deployable JSON
representation. By default, the output will be written to file with the same
name as the input file, but with the extension replaced by 'json'.
positional arguments:
<filename> source file to compile
optional arguments:
-h, --help show this help message and exit
--compact use compact JSON format instead of readable (default)
--sorted sort resulting JSON output by keys
--issue-fmt FMT custom format for issue reporting.
--verbose informational output from the compiler
--deployscript generate deployjson file
--intermediate generate intermediate representation file
--stdout send output to stdout instead of file (default)
--output <filename> Output file, default is filename.json