2024-04-30 18:15:32 +12:00
< p align = "center" >
< a href = "https://github.com/liamcottle/reticulum-webchat" > < img src = "./logo/logo-chat-bubble.png" width = "150" > < / a >
< / p >
< h2 align = "center" > Reticulum WebChat< / h2 >
2024-04-30 18:17:20 +12:00
< p align = "center" >
< a href = "https://discord.gg/APQSQZNV7t" > < img src = "https://img.shields.io/badge/Discord-Liam%20Cottle's%20Discord-%237289DA?style=flat&logo=discord" alt = "discord" / > < / a >
< a href = "https://twitter.com/liamcottle" >< img src = "https://img.shields.io/badge/Twitter- @liamcottle -%231DA1F2?style=flat&logo=twitter" alt = "twitter" /></ a >
< br / >
< a href = "https://ko-fi.com/liamcottle" > < img src = "https://img.shields.io/badge/Donate%20a%20Coffee-liamcottle-yellow?style=flat&logo=buy-me-a-coffee" alt = "donate on ko-fi" / > < / a >
< a href = "./donate.md" > < img src = "https://img.shields.io/badge/Donate%20Bitcoin-3FPBfiEwioWHFix3kZqe5bdU9F5o8mG8dh-%23FF9900?style=flat&logo=bitcoin" alt = "donate bitcoin" / > < / a >
< / p >
2024-04-30 18:15:32 +12:00
## What is Reticulum WebChat?
2024-04-29 04:35:58 +12:00
2024-04-30 15:50:15 +12:00
A simple open-source web based [LXMF ](https://github.com/markqvist/lxmf ) client for [Reticulum ](https://github.com/markqvist/Reticulum ).
2024-04-29 04:35:58 +12:00
2024-05-01 00:07:17 +12:00
< img src = "./screenshots/screenshot.png" >
2024-04-29 04:35:58 +12:00
## Features
2024-04-30 21:46:26 +12:00
- Supports sending and receiving messages between [Reticulum WebChat ](https://github.com/liamcottle/reticulum-webchat ), [Sideband ](https://github.com/markqvist/Sideband/ ) and [Nomadnet ](https://github.com/markqvist/nomadnet ).
2024-04-30 15:50:15 +12:00
- Supports receiving and saving images and attachments sent from Sideband.
2024-05-05 21:13:53 +12:00
- Supports sending images and file attachments.
2024-05-04 21:58:23 +12:00
- Supports saving inbound and outbound messages to a local database.
2024-04-30 15:50:15 +12:00
- Supports sending an announce to the network.
- Supports setting a custom display name to send in your announce.
2024-05-01 00:11:19 +12:00
- Supports viewing and searching peers discovered from announces.
2024-04-29 04:35:58 +12:00
2024-05-10 22:18:21 +12:00
## Beta Features
2024-05-21 18:33:44 +12:00
- Support for Audio Calls to other [Reticulum WebChat ](https://github.com/liamcottle/reticulum-webchat ) users.
- Audio is encoded with [codec2 ](https://github.com/drowe67/codec2 ) to support low bandwidth links.
2024-05-22 16:25:49 +12:00
- Using a microphone requires using the web ui over localhost or https, due to [AudioWorklet ](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorklet ) secure context.
2024-05-22 16:28:46 +12:00
- I have tested two-way audio calls over LoRa with a single hop. It works well when a reasonable bitrate is configured on the RNode.
2024-05-10 23:05:29 +12:00
- Support for browsing pages, and downloading files hosted on Nomad Network Nodes.
2024-05-10 22:18:21 +12:00
> NOTE: micron format parsing is still in development, some pages may not render or work correctly at all.
2024-05-27 23:25:23 +12:00
## Download
You can download the latest version for Windows and Mac from the [releases ](https://github.com/liamcottle/reticulum-webchat/releases ) page.
Alternatively, you can download the source and run it manually from a command line.
See the ["How to use it?" ](#how-to-use-it ) section below on how to do this.
2024-04-29 04:35:58 +12:00
## How does it work?
2024-04-29 16:41:57 +12:00
- A python script ([web.py ](./web.py )) runs a Reticulum instance and a WebSocket server.
2024-05-01 00:12:39 +12:00
- The web page sends and receives LXMF packets encoded in json via the WebSocket.
2024-04-29 04:35:58 +12:00
- Web Browser -> WebSocket -> Python Reticulum -> (configured interfaces) -> (destination)
2024-05-04 21:59:33 +12:00
- LXMF messages sent and received are saved to a local SQLite database.
2024-04-29 04:35:58 +12:00
2024-04-29 04:37:41 +12:00
## How to use it?
You will need to clone the repo, and run `web.py` .
```
git clone https://github.com/liamcottle/reticulum-webchat
cd reticulum-webchat
2024-04-29 14:59:45 +12:00
pip install -r requirements.txt
2024-04-29 04:37:41 +12:00
python web.py
```
2024-04-29 04:35:58 +12:00
2024-04-29 14:54:13 +12:00
> NOTE: You should now be able to access the web interface at http://localhost:8000
2024-04-29 16:45:06 +12:00
For a full list of command line options, you can run;
```
python web.py --help
```
```
2024-05-19 00:53:29 +12:00
usage: web.py [-h] [--host [HOST]] [--port [PORT]] [--headless] [--identity-file IDENTITY_FILE] [--identity-base64 IDENTITY_BASE64] [--generate-identity-file GENERATE_IDENTITY_FILE] [--generate-identity-base64]
[--reticulum-config-dir RETICULUM_CONFIG_DIR] [--storage-dir STORAGE_DIR]
2024-04-29 16:45:06 +12:00
ReticulumWebChat
options:
-h, --help show this help message and exit
--host [HOST] The address the web server should listen on.
--port [PORT] The port the web server should listen on.
2024-05-19 00:53:29 +12:00
--headless Web browser will not automatically launch when this flag is passed.
2024-04-29 16:45:06 +12:00
--identity-file IDENTITY_FILE
Path to a Reticulum Identity file to use as your LXMF address.
--identity-base64 IDENTITY_BASE64
A base64 encoded Reticulum Identity to use as your LXMF address.
2024-05-19 00:53:29 +12:00
--generate-identity-file GENERATE_IDENTITY_FILE
Generates and saves a new Reticulum Identity to the provided file path and then exits.
--generate-identity-base64
Outputs a randomly generated Reticulum Identity as base64 and then exits.
--reticulum-config-dir RETICULUM_CONFIG_DIR
Path to a Reticulum config directory for the RNS stack to use (e.g: ~/.reticulum)
--storage-dir STORAGE_DIR
Path to a directory for storing databases and config files (default: ./storage)
2024-04-29 16:45:06 +12:00
```
2024-04-29 16:10:10 +12:00
## Using an existing Reticulum Identity
2024-05-24 02:02:23 +12:00
The first time you run this application, a new Reticulum identity is generated and saved to `storage/identity` .
2024-04-29 16:10:10 +12:00
2024-05-24 02:02:23 +12:00
If you want to use an existing identity;
2024-04-29 16:10:10 +12:00
2024-05-24 02:02:23 +12:00
- You can overwrite `storage/identity` with another identity file.
- Or, you can pass in a custom identity file path as a command line argument.
To use a custom identity file, provide the `--identity-file` argument followed by the path to your custom identity file.
```
python web.py --identity-file ./custom_identity_file
```
If you would like to generate a new identity, you can use the [rnid ](https://reticulum.network/manual/using.html#the-rnid-utility ) utility provided by Reticulum.
2024-04-29 16:10:10 +12:00
```
2024-05-24 02:02:23 +12:00
rnid --generate ./new_identity_file
2024-04-29 16:32:17 +12:00
```
2024-05-24 02:02:23 +12:00
If you don't have access to the `rnid` command, you can use the following:
2024-04-29 16:32:17 +12:00
```
2024-05-24 02:02:23 +12:00
python web.py --generate-identity-file ./new_identity_file
2024-04-29 16:32:17 +12:00
```
Alternatively, you can provide a base64 encoded private key, like so;
```
python web.py --identity-base64 "GCN6mMhVemdNIK/fw97C1zvU17qjQPFTXRBotVckeGmoOwQIF8VOjXwNNem3CUOJZCQQpJuc/4U94VSsC39Phw=="
2024-04-29 16:10:10 +12:00
```
> NOTE: this is a randomly generated identity for example purposes. Do not use it, it has been leaked!
2024-05-27 21:35:00 +12:00
## Build Electron Application
2024-05-24 01:35:30 +12:00
2024-05-27 22:24:25 +12:00
Reticulum WebChat can be run from source via a command line, as explained above, or as a standalone application.
2024-05-24 01:35:30 +12:00
2024-05-27 22:24:25 +12:00
To run as a standalone application, we need to compile the python script and dependencies to an executable with [cxfreeze ](https://github.com/marcelotduarte/cx_Freeze ) and then build an [Electron ](https://www.electronjs.org/ ) app which includes a bundled browser that can interact with the compiled python executable.
This allows for the entire application to be run by double clicking a single file without the need for a user to manually install python, nor run any commands in a command line application.
2024-05-27 21:35:00 +12:00
2024-05-27 21:57:56 +12:00
To build a `.exe` when running on Windows or a `.dmg` when running on a Mac, run the following;
2024-05-27 21:35:00 +12:00
```
2024-05-27 21:39:28 +12:00
pip install -r requirements.txt
2024-05-27 21:35:47 +12:00
npm install
2024-05-27 21:35:00 +12:00
npm run dist
```
> Note: cxfreeze only supports building an executable for the current platform. You will need a Mac to build for Mac, and a Windows PC to build for Windows.
2024-05-24 02:44:54 +12:00
2024-05-27 21:57:56 +12:00
Once completed, you should have a `.exe` or a `.dmg` in the `dist` folder.
2024-04-29 04:44:42 +12:00
## TODO
2024-05-24 02:41:22 +12:00
- [ ] auto build and release windows and macos binaries via github actions
2024-04-30 15:51:41 +12:00
- [ ] conversations/contacts list ui with unread indicators
2024-05-01 00:16:10 +12:00
- [ ] button to add peer to contacts, and show a tab for contacts, separate from peers list
2024-04-30 15:50:15 +12:00
- [ ] allow setting a custom name to show for a contact
- [ ] button to forget peers and contacts
2024-04-30 21:07:01 +12:00
- [ ] optimise ui to work nicely on a mobile device, such as Android/iOS
2024-04-30 21:16:02 +12:00
- [ ] support for managing Reticulum config/interfaces via the web ui
2024-05-27 13:58:34 +12:00
- [ ] support for micron input fields, to allow interacting with pages like Retipedia
2024-05-24 02:09:09 +12:00
## License
MIT