Skip to content
This repository has been archived by the owner on Aug 13, 2020. It is now read-only.

Tools

Jump to bottom
Per Persson edited this page Jul 7, 2017 · 10 revisions

The Calvin tools consists of the following commands

explained below.

csdocs

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

Full usage description:

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$

csruntime

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.

Full usage description:

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.

cscontrol

This is a generic command to send control commands and queries to runtimes, but the most common use of cscontrol is deploying applications.

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

Other uses

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

Full usage description:

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

csviz

This tool allows you to visualize an application as a data flow graph.

Full usage description:

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.

csmanage

Manage the host's actor store and credentials, where the most common use is to install actors and components.

Installing 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

Installing actors

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

Full usage description:

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

csweb

This command starts a webserver, serving a Calvin debugging tool.

csweb --port 8000 &
firefox http://localhost:8000

Full usage description:

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

cscompile

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.

Full usage description:

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
Clone this wiki locally