Sideband/README.md

295 lines
17 KiB
Markdown
Raw Normal View History

2022-10-25 06:52:41 -06:00
Sideband <img align="right" src="https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg"/>
=========
2022-04-07 13:03:53 -06:00
2024-03-26 11:11:26 -06:00
Sideband is an extensible LXMF messaging client, situational awareness tracker and remote control and monitoring system for Android, Linux, macOS and Windows. It allows you to communicate with other people or LXMF-compatible systems over Reticulum networks using LoRa, Packet Radio, WiFi, I2P, Encrypted QR Paper Messages, or anything else Reticulum supports.
2022-04-07 13:03:53 -06:00
2022-10-03 18:33:36 -06:00
![Screenshot](https://github.com/markqvist/Sideband/raw/main/docs/screenshots/devices_small.webp)
2022-04-07 13:03:53 -06:00
2022-10-03 16:34:21 -06:00
Sideband is completely free, end-to-end encrypted, permission-less, anonymous and infrastructure-less. Sideband uses the peer-to-peer and distributed messaging system [LXMF](https://github.com/markqvist/lxmf "LXMF"). There is no sign-up, no service providers, no "end-user license agreements", no data theft and no surveillance. You own the system.
2022-04-07 13:03:53 -06:00
2022-07-07 16:06:35 -06:00
This also means that Sideband operates differently than what you might be used to. It does not need a connection to a server on the Internet to function, and you do not have an account anywhere. Please read the Guide section included in the program, to get an understanding of how Sideband differs from other messaging systems.
2024-06-29 14:12:07 -06:00
# Functionality & Features
2024-06-07 10:50:19 -06:00
2024-03-26 07:32:49 -06:00
Sideband provides many useful and interesting functions, such as:
2024-06-07 10:46:20 -06:00
- **Secure** and **self-sovereign** messaging using the LXMF protocol over Reticulum.
- **Image** and **file transfers** over all supported mediums.
- **Audio messages** that work even over **LoRa** and **radio links**, thanks to [Codec2](https://github.com/drowe67/codec2/) and [Opus](https://github.com/xiph/opus) encoding.
- Secure and direct P2P **telemetry and location sharing**. No third parties or servers ever have your data.
- Situation display on both online and **locally stored offline maps**.
2024-03-26 07:32:49 -06:00
- Geospatial awareness calculations.
2024-06-07 10:46:20 -06:00
- Exchanging messages through **encrypted QR-codes on paper**, or through messages embedded directly in **lxm://** links.
- Using **Android devices as impromptu Reticulum routers** (*Transport Instances*), for setting up or extending networks easily.
2024-09-19 15:55:20 -06:00
- Remote **command execution and response engine**, with built-in commands, such as `ping`, `signal` reports and `echo`, and **full plugin expandability**.
2024-06-07 10:46:20 -06:00
- Remote **telemetry querying**, with strong, secure and cryptographically robust authentication and control.
- **Plugin system** that allows you to easily **create your own commands**, services and telemetry sources.
2022-04-07 13:03:53 -06:00
2024-06-04 16:32:44 -06:00
Sideband is fully compatible with other LXMF clients, such as [MeshChat](https://github.com/liamcottle/reticulum-meshchat), and [Nomad Network](https://github.com/markqvist/nomadnet). The Nomad Network client also allows you to easily host Propagation Nodes for your LXMF network, and more.
2022-04-07 13:03:53 -06:00
2024-06-29 09:55:44 -06:00
# Installation
2024-06-29 14:12:07 -06:00
Sideband can run on most computing devices, but installation methods vary by device type and operating system. For installation instructions, please find the relevant section below.
2024-06-29 14:18:32 -06:00
- [Android](#on-android)
- [Linux](#on-linux)
- [Raspberry Pi](#on-raspberry-pi)
- [MacOS](#on-macos)
- [Windows](#on-windows)
2024-06-29 09:55:44 -06:00
## On Android
2022-07-07 16:06:35 -06:00
2024-11-25 13:47:15 -07:00
For your Android devices, you can install Sideband through F-Droid, by adding the [Between the Borders Repo](https://reticulum.betweentheborders.com/fdroid/repo/), or you can download an [APK on the latest release page](https://github.com/markqvist/Sideband/releases/latest). Both sources are signed with the same release keys, and can be used interchangably.
2024-05-21 10:41:15 -06:00
After the application is installed on your Android device, it is also possible to pull updates directly through the **Repository** section of the application.
2022-07-07 16:06:35 -06:00
2024-06-29 09:55:44 -06:00
## On Linux
2022-10-03 18:39:55 -06:00
2024-09-18 04:36:20 -06:00
On all Linux-based operating systems, Sideband is available as a `pipx`/`pip` package. This installation method **includes desktop integration**, so that Sideband will show up in your applications menu and launchers. Below are install steps for the most common recent Linux distros. For Debian 11, see the end of this section.
2024-06-07 10:42:46 -06:00
2024-11-26 06:46:05 -07:00
**Please note!** The very latest Python release, Python 3.13 is currently **not** compatible with the Kivy framework, that Sideband uses to render its user interface. If your Linux distribution uses Python 3.13 as its default Python installation, you will need to install an earlier version as well. Using [the latest release of Python 3.12](https://www.python.org/downloads/release/python-3127/) is recommended.
2024-06-29 10:03:21 -06:00
You will first need to install a few dependencies for audio messaging and Codec2 support to work:
2022-07-07 16:06:35 -06:00
```bash
2024-09-18 04:36:20 -06:00
# For Debian (12+), Ubuntu (22.04+) and derivatives
2024-06-29 09:55:44 -06:00
sudo apt install pipx python3-pyaudio python3-dev build-essential libopusfile0 portaudio19-dev codec2 xclip xsel
2024-06-07 06:48:17 -06:00
2024-06-29 09:55:44 -06:00
# For Manjaro and derivatives
pamac install python-pipx python-pyaudio base-devel codec2 xclip xsel
2024-06-07 06:48:17 -06:00
2024-06-29 09:55:44 -06:00
# For Arch and derivatives
sudo pacman -Sy python-pipx python-pyaudio base-devel codec2 xclip xsel
2024-06-29 09:59:19 -06:00
```
2024-06-29 10:03:21 -06:00
Once those are installed, install the Sideband application itself:
```bash
# Finally, install Sideband using pipx:
pipx install sbapp
2024-11-26 06:46:05 -07:00
# If you need to specify a specific Python version,
# use something like the following:
pipx install sbapp --python python3.12
2024-06-29 10:03:21 -06:00
```
After installation, you can now run Sideband in a number of different ways:
2024-06-29 09:59:19 -06:00
```bash
2024-06-29 09:55:44 -06:00
# If this is the first time installing something with pipx,
# you may need to use the following command, to make your
# installed applications available. You'll probably need
# to close and reopen your terminal after this.
pipx ensurepath
2024-06-07 10:46:20 -06:00
2024-06-29 09:55:44 -06:00
# The first time you run Sideband, you will need to do it
# from the terminal:
sideband
2024-06-04 07:49:17 -06:00
2024-06-29 09:55:44 -06:00
# At the first launch, it will add an application icon
# to your launcher or apps menu. You may need to log out
# of your session, and back in for the application to
# show up in your launcher, depending on your distro.
2024-05-05 11:29:12 -06:00
2024-06-29 09:55:44 -06:00
# You can also run Sideband in headless daemon
# mode, for example as a telemetry collector:
sideband --daemon
2023-08-15 04:47:54 -06:00
2024-06-29 09:55:44 -06:00
# You can also run Sideband with more verbose
# log output enabled:
sideband -v
2023-08-15 04:47:54 -06:00
```
2024-06-29 09:55:44 -06:00
You can also install Sideband in various alternative ways:
2024-06-07 10:42:46 -06:00
```bash
2024-06-29 09:55:44 -06:00
# Install Sideband via pip instead of pipx:
pip install sbapp
2024-06-07 10:42:46 -06:00
2024-06-29 09:55:44 -06:00
# Or, if pip is externally managed:
pip install sbapp --break-system-packages
2024-06-07 10:42:46 -06:00
2024-06-29 09:55:44 -06:00
# Or, if you intend to run Sideband in headless
# daemon mode, you can also install it without
# any of the normal UI dependencies:
pip install sbapp --no-dependencies
2024-06-07 10:42:46 -06:00
2024-11-26 06:46:05 -07:00
# In the case of using --no-dependencies, you
# will still need to manually install the RNS
# and LXMF dependencies:
2024-06-29 09:55:44 -06:00
pip install rns lxmf
2024-09-18 04:36:20 -06:00
# Install Sideband on Debian 11 and derivatives:
sudo apt install python3-pip python3-pyaudio python3-dev build-essential libopusfile0 portaudio19-dev codec2 xclip xsel
pip install sbapp
# On Debian 11, run Sideband manually via the
# terminal once to install desktop integration:
python3 -m sbapp.main
2024-06-07 10:42:46 -06:00
```
2024-06-29 14:12:07 -06:00
## On Raspberry Pi
You can install Sideband on all Raspberry Pi models that support 64-bit operating systems, and can run at least Python version 3.11. Since some of Sideband's dependencies don't have pre-built packages ready for 64-bit ARM processors yet, you'll need to install a few extra packages, that will allow building these while installing.
Aditionally, the `pycodec2` package needs to be installed manually. I have provided a pre-built version, that you can download and install with a single command, or if you don't want to trust my pre-built version, you can [build and install it from source yourself](https://github.com/gregorias/pycodec2/blob/main/DEV.md).
The install instructions below assume that you are installing Sideband on 64-bit Raspberry Pi OS (based on Debian Bookworm). If you're running something else on your Pi, you might need to modify some commands slightly. To install Sideband on Raspberry Pi, follow these steps:
```bash
# First of all, install the required dependencies:
sudo apt install python3-pip python3-pyaudio python3-dev python3-cryptography build-essential libopusfile0 libsdl2-dev libavcodec-dev libavdevice-dev libavfilter-dev portaudio19-dev codec2 libcodec2-1.0 xclip xsel
# If you don't want to compile pycodec2 yourself,
# download the pre-compiled package provided here
wget https://raw.githubusercontent.com/markqvist/Sideband/main/docs/utilities/pycodec2-3.0.1-cp311-cp311-linux_aarch64.whl
# Install it:
pip install ./pycodec2-3.0.1-cp311-cp311-linux_aarch64.whl --break-system-packages
# You can now install Sideband
pip install sbapp --break-system-packages
# Restart your Raspberry Pi
sudo reboot
# Everything is ready! You can now run Sideband
# from the terminal, or from the application menu
sideband
```
2024-06-29 09:55:44 -06:00
## On macOS
2023-08-15 03:24:54 -06:00
2024-11-25 13:47:15 -07:00
You can download a DMG with Sideband for macOS (ARM and Intel) from the [latest release page](https://github.com/markqvist/Sideband/releases/latest). If you install Sideband from the DMG file, it is still recommended to install the `rns` package via the `pip` or `pipx` package manager, so you can use the RNS utility programs, like `rnstatus` to see interface and connectivity status from the terminal.
2023-08-15 03:24:54 -06:00
2024-11-26 06:46:05 -07:00
**Please note!** The very latest Python release, Python 3.13 is currently **not** compatible with the Kivy framework, that Sideband uses to render its user interface. If your version of macOS uses Python 3.13 as its default Python installation, you will need to install an earlier version as well. Using [the latest release of Python 3.12](https://www.python.org/downloads/release/python-3127/) is recommended.
2024-11-25 13:47:15 -07:00
2024-11-26 06:46:05 -07:00
To install Sideband via `pip`, follow these instructions:
2023-08-15 03:24:54 -06:00
2024-05-21 10:39:10 -06:00
```bash
2024-09-11 10:04:31 -06:00
# Install Sideband and dependencies on macOS using pip:
pip3 install sbapp --user --break-system-packages
2024-05-21 10:39:10 -06:00
2024-11-26 06:46:05 -07:00
# Optionally install RNS command line utilities:
pip3 install rns
# Run Sideband from the terminal:
2024-06-04 07:49:17 -06:00
python3 -m sbapp.main
2024-11-26 06:46:05 -07:00
# Enable debug logging:
python3 -m sbapp.main -v
# Start Sideband in daemon mode:
python3 -m sbapp.main -d
2024-06-04 07:49:17 -06:00
# If you add your pip install location to
# the PATH environment variable, you can
# also run Sideband simply using:
2024-05-21 10:39:10 -06:00
sideband
2023-08-15 03:24:54 -06:00
```
2024-06-29 09:55:44 -06:00
## On Windows
2023-09-20 18:11:04 -06:00
2024-11-29 05:50:26 -07:00
To install Sideband on Windows, you have two options available: An easy to install pre-built executable package, or a source package install for more advanced setups.
2024-11-26 06:46:05 -07:00
2024-11-29 05:50:26 -07:00
#### Prebuilt Executable
2023-09-20 18:11:04 -06:00
2024-11-29 05:50:26 -07:00
Simply download the packaged Windows ZIP file from the [latest release page](https://github.com/markqvist/Sideband/releases/latest), unzip the file, and run `Sideband.exe` from the unzipped directory. You can create desktop or start menu shortcuts from this executable if needed.
2024-06-29 14:12:07 -06:00
2024-11-29 05:50:26 -07:00
When running Sideband for the first time, a default Reticulum configuration file will be created, if you don't already have one. If you don't have any existing Reticulum connectivity available locally, you may want to edit the file, located at `C:\Users\USERNAME\.reticulum\config` and manually add an interface that provides connectivity to a wider network. If you just want to connect over the Internet, you can add one of the public hubs on the [Reticulum Testnet](https://reticulum.network/connect.html).
Though the ZIP file contains everything necessary to run Sideband, it is also recommended to install the Reticulum command line utilities separately, so that you can use commands like `rnstatus` and `rnsd` from the command line. This will make it easier to manage Reticulum connectivity on your system. If you do not already have Python installed on your system, [download and install it](https://www.python.org/downloads/) first.
2023-09-20 18:11:04 -06:00
2024-11-29 05:50:26 -07:00
**Important!** When asked by the installer, make sure to add the Python program to your `PATH` environment variables. If you don't do this, you will not be able to use the `pip` installer, or run any of the installed commands. When Python has been installed, you can open a command prompt and install the Reticulum package via `pip`:
2023-09-20 18:11:04 -06:00
```bash
2024-11-29 05:50:26 -07:00
pip install rns
2023-09-20 18:11:04 -06:00
```
2024-11-29 05:50:26 -07:00
#### Source Package Install
2024-05-21 10:39:10 -06:00
2024-11-29 05:50:26 -07:00
For more advanced setups, including the ability to run Sideband in headless daemon mode, enable debug logging output, configuration import and export and more, you may want to install it from the source package via `pip` instead.
2024-11-29 05:53:47 -07:00
In this case, you will need to [download and install the latest supported version of Python](https://www.python.org/downloads/release/python-3127/) (currently Python 3.12.7), since very latest Python release, Python 3.13 is currently **not** compatible with the Kivy framework, that Sideband uses to render its user interface. The binary package already includes a compatible Python version, so if you are running Sideband from that, there is no need to install a specific version of Python.
2024-11-29 05:50:26 -07:00
When Python has been installed, you can open a command prompt and install Sideband via `pip`:
```bash
pip install sbapp
```
2024-11-29 05:53:47 -07:00
The Sideband application can now be launched by running the command `sideband` in the command prompt. If needed, you can create a shortcut for Sideband on your desktop or in the start menu.
Since this installation method automatically installs the `rns` and `lxmf` packages as well, you will also have access to using all the included RNS and LXMF utilities like `rnstatus`, `rnsd` and `lxmd` on your system.
2024-05-21 10:39:10 -06:00
2024-06-29 14:12:07 -06:00
# Paper Messaging Example
2022-11-28 04:12:11 -07:00
You can try out the paper messaging functionality by using the following QR-code. It is a paper message sent to the LXMF address `6b3362bd2c1dbf87b66a85f79a8d8c75`. To be able to decrypt and read the message, you will need to import the following base32-encoded Reticulum Identity into the app:
`3BPTDTQCRZPKJT3TXAJCMQFMOYWIM3OCLKPWMG4HCF2T4CH3YZHVNHNRDU6QAZWV2KBHMWBNT2C62TQEVC5GLFM4MN25VLZFSK3ADRQ=`
2022-11-27 10:09:23 -07:00
You can import the identity into Sideband in the **Encryption Keys** part of the program. After the you have imported the identity, you can scan the following QR-code and open it in the app, where it will be decrypted and added to your messages.
2022-11-28 04:12:11 -07:00
<p align="center"><img width="50%" src="https://raw.githubusercontent.com/markqvist/LXMF/master/docs/paper_msg_test.png"/></p>
You can also find the entire message in <a href="lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I">this link</a>:
`lxm://azNivSwdv4e2aoX3mo2MdTAozuI7BlzrLlHULmnVgpz3dNT9CMPVwgywzCJP8FVogj5j_kU7j7ywuvBNcr45kRTrd19c3iHenmnSDe4VEd6FuGsAiT0Khzl7T81YZHPTDhRNp0FdhDE9AJ7uphw7zKMyqhHHxOxqrYeBeKF66gpPxDceqjsOApvsSwggjcuHBx9OxOBy05XmnJxA1unCKgvNfOFYc1T47luxoY3c0dLOJnJPwZuFRytx2TXlQNZzOJ28yTEygIfkDqEO9mZi5lgev7XZJ0DvgioQxMIyoCm7lBUzfq66zW3SQj6vHHph7bhr36dLOCFgk4fZA6yia2MlTT9KV66Tn2l8mPNDlvuSAJhwDA_xx2PN9zKadCjo9sItkAp8r-Ss1CzoUWZUAyT1oDw7ly6RrzGBG-e3eM3CL6u1juIeFiHby7_3cON-6VTUuk4xR5nwKlFTu5vsYMVXe5H3VahiDSS4Q1aqX7I`
On operating systems that allow for registering custom URI-handlers, you can click the link, and it will be decoded directly in your LXMF client. This works with Sideband on Android.
2024-06-29 14:12:07 -06:00
# Support Sideband Development
2022-07-08 09:04:41 -06:00
You can help support the continued development of open, free and private communications systems by donating via one of the following channels:
- Monero:
2024-02-16 09:54:22 -07:00
```
2022-07-08 09:04:41 -06:00
84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
```
- Ethereum
```
2024-02-16 09:49:21 -07:00
0xFDabC71AC4c0C78C95aDDDe3B4FA19d6273c5E73
2022-07-08 09:04:41 -06:00
```
- Bitcoin
```
2024-02-16 09:49:21 -07:00
35G9uWVzrpJJibzUwpNUQGQNFzLirhrYAH
2022-07-08 09:04:41 -06:00
```
2022-10-03 18:33:36 -06:00
- Ko-Fi: https://ko-fi.com/markqvist
2022-10-03 18:44:16 -06:00
<br/>
2024-06-29 14:12:07 -06:00
# Development Roadmap
2022-11-17 05:46:34 -07:00
2024-03-26 07:32:49 -06:00
- <s>Secure and private location and telemetry sharing</s>
- <s>Including images in messages</s>
- <s>Sending file attachments</s>
- <s>Offline and online maps</s>
- <s>Paper messages</s>
- <s>Using Sideband as a Reticulum Transport Instance</s>
- <s>Encryption keys export and import</s>
- <s>Plugin support for commands, services and telemetry</s>
2024-05-05 11:39:42 -06:00
- <s>Adding Linux .desktop file integration</s>
2024-06-04 16:30:39 -06:00
- <s>Sending voice messages (using Codec2 and Opus)</s>
2022-11-17 05:46:34 -07:00
- Implementing the Local Broadcasts feature
2024-03-26 07:32:49 -06:00
- LXMF sneakernet functionality
- Network visualisation and test tools
- A debug log viewer
- Better message sorting mechanism
2022-11-17 05:46:34 -07:00
- Fix I2P status not being displayed correctly when the I2P router disappears unexpectedly
2024-03-26 07:32:49 -06:00
- Adding a Nomad Net page browser
2022-11-17 05:46:34 -07:00
2024-06-29 14:12:07 -06:00
# License
2022-11-01 16:33:50 -06:00
Unless otherwise noted, this work is licensed under a [Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License][cc-by-nc-sa].
2022-10-25 06:52:41 -06:00
2022-11-01 16:33:50 -06:00
Permission is hereby granted to use Sideband in binary form, for any and all purposes, and to freely distribute binary copies of the program, so long as no payment or compensation is charged or received for such distribution or use.
<img src="https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png" align="right">
2022-10-25 06:52:41 -06:00
[cc-by-nc-sa]: http://creativecommons.org/licenses/by-nc-sa/4.0/
[cc-by-nc-sa-image]: https://licensebuttons.net/l/by-nc-sa/4.0/88x31.png
[cc-by-nc-sa-shield]: https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg
2022-10-04 02:37:31 -06:00
*Device screenshots generated with [deviceframes](https://deviceframes.com). Thanks!*