remoteSwitch is a cross platform application which makes your (antenna/band/power...) switches available on the network.
To get a first impression, you're welcome to play with our public demo at demo.switch.shackbus.org.
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.
- Multi Purpose Switch GPIO (e.g Bandswitch, Beverages, etc.)
- Stackmatch GPIO (Stackmatch, Combiners, 4-Squares. etc)
- Dummy Switch (for testing purposes without hardware)
- EA4TX Remotebox
- NATS
- HTTP & Websockets for the WebUI
remoteSwitch is published under the permissive MIT license.
You can download a zip archive with the compiled binary for MacOS (AMD64), Linux (386/AMD64/ARM/ARM64) and Windows (386/AMD64) from the releases page. remoteSwitch works particularly well on SoC boards like the Raspberry / Orange / Banana Pis. The application itself is just a single executable.
remoteSwitch only depends on a few go libraries which are needed at compile time. There are no runtime dependencies.
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
The nats server allows you to expose an Switch on a nats.io broker. The broker
can be located within your local lan or somewhere on the internet.
Usage:
remoteSwitch server nats [flags]
Flags:
-p, --broker-port int Broker Port (default 4222)
-u, --broker-url string Broker URL (default "localhost")
-h, --help help for nats
-P, --password string NATS Password
-U, --username string NATS Username
Global Flags:
--config string config file (default is $HOME/.remoteSwitch.yaml)
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. The example folder in this repository contains additional example configurations.
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:
$ ./nats-server
[62418] 2020/04/11 02:46:09.413858 [INF] Starting nats-server version 2.1.6
[62418] 2020/04/11 02:46:09.413959 [INF] Git commit [not set]
[62418] 2020/04/11 02:46:09.414150 [INF] Listening for client connections on 0.0.0.0:4222
[62418] 2020/04/11 02:46:09.414156 [INF] Server id is NDCPYYXYRSKD6PIBTS7YHZGEBWIN3CBPRH232CMHUWU3NXBQTTBBQRNF
[62418] 2020/04/11 02:46:09.414158 [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
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. You can run several instances of the web server. This might be handy if you have to deal with lan/wan restrictions or if you need redundancy.
Simply launch:
$ ./remoteSwitch web
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:
- Pflags (e.g. -p 4040)
- Values from config file
- Default values
The GPIO switches are pretty flexible in configuration and should be able to cope with most user requirements.
If an error occurs 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 on Linux or NSSM - the Non-Sucking Service Manager on Windows.
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 behavior.
If you file a bug report, please include always the version of remoteSwitch you are running:
$ remoteSwitch.exe version
copyright Tobias Wellnitz, DH1TW, 2020
remoteSwitch Version: v0.1.0, darwin/amd64, BuildDate: 2020-04-11T02:50:26+02:00, Commit: 528027d
The auto generated documentation can be found at godoc.org.
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
All critical 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 race detector might not be available on all platforms / operating systems.