==========================
Satlab Control Application
==========================

The Satlab Control Application, ``satctl``, can be used to communicate with Satlab products using CSP via CAN-bus, UART/RS-422 or multicast Ethernet.

Dependencies
============

Python, Jinja2 and GCC are required for building. The CAN-bus support requires a Linux kernel with SocketCAN support (CONFIG_CAN).

Building
========

The application is built using the `Waf build system <https://waf.io/>`_.

To build, run::

   satlab@satlab:~$ python waf distclean configure build

To also build python bindings, run::

   satlab@satlab:~$ python waf distclean configure --satctl-enable-python-bindings build

Examples of how to use the bindings can be found in the ``examples/bindings`` directory.

Python Virtual Environment
==========================

The application can be built and installed in a virtual Python environment like this.

Create the venv::

   satlab@satlab:~$ python -m venv venvs/satctl

Activate the new venv::

   satlab@satlab:~$ source venvs/satctl/bin/activate

Install requirements::

   satlab@satlab:~$ pip install -r requirements.txt

Build and install satctl with bindings in the venv::

   satlab@satlab:~$ python waf distclean configure install --satctl-enable-python-bindings --prefix=venvs/satctl

satctl and the python bindings can now be used in the venv.

Running
=======

The application binary is located in the ``build`` directory. To show available command line options, run::

    satlab@satlab:~$ ./build/satctl -h
    usage: satctl [options] [command]

    Satlab Control Application v1.20.0
    Copyright (c) 2014-2023 Satlab A/S <satlab@satlab.com>

    Options:
      -c, --can=DEVICE[@RATE]    Enable CAN transport interface
      -m, --mcast=DEVICE         Enable MCAST transport interface
      -u, --uart=DEVICE[@RATE]   Enable UART/KISS transport interface
      -s, --slgnd=HOST[:PORT]    Enable SLGND transport interface
      -e, --udp=DEVICE           Enable UDP transport interface
          --can-promisc          Enable promiscuous mode CAN interfaces
      -z, --zmqhub=HOST          Enable ZMQHUB transport interface
      -Z, --zmqproxy             Start built-in ZMQPROXY for ZMQHUB
      -i, --id=ID                Show ID as prompt and CSP ident hostname
      -n, --node=NODE            Use NODE as own CSP address
      -r, --routes=ROUTES        Use ROUTES as CSP routing table
      -k, --key=KEY              Use KEY as CSP XTEA/HMAC key
      -p, --pingalive=NODE       Ping NODE every second in background
      -h, --help                 Print this help and exit
      -v, --verbose              Enable verbose output
          --version              Print satctl version number

One or more interface must be selected. To use 1 Mbit/s CAN-bus on the ``can0`` SocketCAN interface, the application can e.g. be run as::

    satlab@satlab:~$ ./build/satctl --can=can0@1000000
    Satlab Control Application v1.20.0
    Copyright (c) 2014-2023 Satlab A/S <satlab@satlab.com>

    Run 'help' for a list of available commands

    [satctl] polaris ping
    Reply in 0.737 ms
    [satctl] polaris prop list store
    Property        Type    Value
    enable          bool    true
    seq             u32     607651
    stored          u32     261106 frames

Run ``help`` to show a list of built-in commands. The application is closed by running ``exit`` or pressing ``^D``.
