remoteswitch

README

RemoteSwitch

remoteSwitch is a cross platform application which makes your (antenna/band/power...) switches available on the network.

remoteSwitch is written in the programing language Go.

ADVICE: This project is under development. The parameters and the ICD are still not stable and subject to change until the first major version has been reached.

Supported switch types

• Multi Purpose Switch GPIO (e.g Bandswitch, Beverages, etc.)
• Stackmatch GPIO (Stackmatch, Combiners, 4-Squares. etc)
• Dummy Switch (for testing purposes without hardware)

Supported Transportation Protocols

• NATS
• HTTP & Websockets for the WebUI

License

remoteSwitch is published under the permissive MIT license.

Download

You can download a tarball / zip archive with the compiled binary for MacOS (AMD64), Linux (386/AMD64/ARM/ARM64) and Windows (386/AMD64) from the releases page.

remoteSwitch works particulary well on SoC boards like the Raspberry / Orange / Banana Pis.

remoteSwitch is just a single executable.

Dependencies

remoteSwitch only depends on a few go libraries which are needed at compile time. There are no runtime dependencies.

Getting started

remoteSwitch provides a series of nested commands and flags.

$ ./remoteSwitch

Network interface for Switches

Usage:
  remoteSwitch [command]

Available Commands:
  help        Help about any command
  server      Switch Server
  version     Print the version number of remoteSwitch
  web         webserver providing access to all switches on the network

Flags:
      --config string   config file (default is $HOME/.remoteSwitch.yaml)
  -h, --help            help for remoteSwitch

Use "remoteSwitch [command] --help" for more information about a command.

So let's fire up a remoteSwitch server for a dummy 6x2 antenna/bandswitch.

To get a list of supported flags for the nats server, execute:

$ ./remoteSwitch server nats --help

While some of the parameters can be set via pflags, the switch configuration in particular MUST be set in a config file due to its complexity.

As a starting point you might want to download a copy of the example configuration file ./remoteSwitch.toml which comes conveniently pre-configured for our dummy antenna/bandswitch.

NATS is an open source, lightweight, high performance message broker which is needed for the underlying communication. You can decide where to run your NATS instance. You can run it on your local machine, in a VPN or expose it to the internet. You can download the NATS broker here.

run the NATS broker:

$ ./gnatsd

[27781] 2019/01/10 21:36:41.886770 [INF] Starting nats-server version 1.0.4
[27781] 2019/01/10 21:36:41.887812 [INF] Listening for client connections on 0.0.0.0:4222
[27781] 2019/01/10 21:36:41.887821 [INF] Server is ready

Let's execute:

$ ./remoteSwitch server nats --config=.remoteSwitch.toml

Using config file:
/home/dh1tw/.remoteSwitch.toml
2019/01/11 23:50:20 Listening on shackbus.switch.6x2_Bandswitch
2019/01/11 23:50:20 Registering node: shackbus.switch.6x2 Bandswitch-45988210-15f3-11e9-b0fa-6c4008b0322c

Web Interface

remoteSwitch comes with a built-in web server which allows to control all switches connected to the same NATS broker. All instances of remoteSwitch are automatically discovered.

Simply launch:

$ ./remoteSwitch web

Config file

The repository contains a ready-to-go example configuration file. By convention it is called .remoteSwitch.[yaml|toml|json] and is located by default either in the home directory or the directory where the remoteSwitch executable is located. The format of the file can either be in yaml, toml, or json.

The first line after starting remoteSwitch will indicate if / which config file has been found.

More complex example configuration files are located in the folder examples.

If you want to run several remoteSwitches on the same machine, you have to create a configuration file for each of them and specify them with the --config flag.

Priority:

1. Pflags (e.g. -p 4040)
2. Values from config file
3. Default values

The GPIO switches are pretty flexible in configuration and should be able to cope with most user requirements.

Behaviour on Errors

If an error occures from which remoteSwitch can not recover, the application exits. It is recommended to execute remoteSwitch as a service under the supervision of a scheduler like systemd.

Bug reports, Questions & Pull Requests

Please use the Github Issue tracker to report bugs and ask questions! If you would like to contribute to remoteSwitch, pull requests are welcome! However please consider to provide unit tests with the PR to verify the proper behaviour.

If you file a bug report, please include always the version of remoteSwitch you are running:

$ remoteSwitch.exe version

copyright Tobias Wellnitz, DH1TW, 2019
remoteSwitch Version: 0.1.0, darwin/amd64, BuildDate: 2019-01-09T00:58:00+02:00, Commit: 338ff13

Documentation

The auto generated documentation can be found at godoc.org.

How to build

In order to compile remoteSwitch from the sources, you need to have Go installed and configured.

This his how to checkout and compile remoteSwitch under Linux/MacOS:

$ go get -d github.com/dh1tw/remoteSwitch
$ cd $GOPATH/src/github.com/remoteSwitch
$ make

How to execute the tests

All critial packages have their own set of unit tests. The tests can be executed with the following commands:

$ cd $GOPATH/src/github.com/remoteSwitch
$ go test -v -race ./...

The datarace detector might not be available on all platforms / operating systems.