From f9e24f4cfcf48482405e210058679b0121c22910 Mon Sep 17 00:00:00 2001 From: mycognosist Date: Thu, 4 Mar 2021 08:36:37 +0000 Subject: [PATCH] Bump version, add routes docs and packaging details --- src/software/web_interface.md | 98 +++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 5 deletions(-) diff --git a/src/software/web_interface.md b/src/software/web_interface.md index 20b8afc..7d619d8 100644 --- a/src/software/web_interface.md +++ b/src/software/web_interface.md @@ -1,16 +1,16 @@ # Web Interface -[![GitHub logo](/assets/github_logo.png "peach-buttons GitHub repository")](https://github.com/peachcloud/peach-buttons) +[![GitHub logo](/assets/github_logo.png "peach-buttons GitHub repository")](https://github.com/peachcloud/peach-buttons) [![Build Status](https://travis-ci.com/peachcloud/peach-web.svg?branch=master)](https://travis-ci.com/peachcloud/peach-web) ![Version badge](https://img.shields.io/badge/version-0.4.2-.svg) [peach-web](https://github.com/peachcloud/peach-web) provides a web interface for monitoring and interacting with the PeachCloud device. This allows administration of the single-board computer (ie. Raspberry Pi) running PeachCloud, as well as the ssb-server and related plugins. -### Design +## Design `peach-web` is written primarily in Rust and presents a web interface for interacting with the device. The stack currently consists of [Rocket](https://rocket.rs/) (Rust web framework), [Tera](https://tera.netlify.com/docs/installation/) (Rust template engine inspired by Jinja2 and the Django template language), HTML, CSS and JavaScript. Additional functionality is provided by JSON-RPC clients for the `peach-network` and `peach-stats` microservices. HTML is rendered server-side. Request handlers call JSON-RPC microservices and serve HTML and assets. A JSON API is exposed for remote calls and dynamic client-side content updates via vanilla JavaScript following [unobstructive design principles](https://www.w3.org/wiki/The_principles_of_unobtrusive_JavaScript). A basic Websockets server is included, though is not currently utilised. Each Tera template is passed a context object. In the case of Rust, this object is a `struct` and must implement `Serialize`. The fields of the context object are available in the context of the template to be rendered. -### Directory Tree +## Directory Tree ```bash . @@ -57,7 +57,61 @@ HTML is rendered server-side. Request handlers call JSON-RPC microservices and s │   └── shutdown.html.tera ``` -### Environment +## WEB ROUTES (`src/routes.rs`) + +| Endpoint | Method | Parameters | Description | +| --- | --- | --- | --- | +| `/` | GET | | Home | +| `/device` | GET | | Device status overview | +| `/device/reboot` | GET | | Reboot device | +| `/device/shutdown` | GET | | Shutdown device | +| `/login` | GET | | Login form | +| `/network` | GET | | Network status overview | +| `/network/ap/activate` | GET | | Activate WiFi access point mode | +| `/network/wifi` | GET | | List of networks | +| `/network/wifi?` | GET | `ssid` | Details of a single network | +| `/network/wifi/activate` | GET | | Activate WiFi client mode | +| `/network/wifi/add` | GET | `ssid` (optional - prepopulation value of SSID in form) | Add a WiFi network | +| `/network/wifi/add` | POST | `ssid` & `pass` | Submit form to add a WiFi network | +| `/network/wifi/connect` | POST | `ssid` | Connect to the given WiFi network | +| `/network/wifi/disconnect` | POST | `ssid` | Disconnect from currently associated WiFi network | +| `/network/wifi/forget` | POST | `ssid` | Submit form to forget a saved WiFi network | +| `/network/wifi/modify?` | GET | `ssid` | Form for updating a WiFi network password | +| `/network/wifi/modify` | POST | `ssid` & `pass` | Submit form to update a WiFi network password | +| `/network/wifi/usage` | GET | | Network data usage values and a form to update alert thresholds | +| `/network/wifi/usage` | POST | `rx_warn`, `rx_cut`, `tx_warn`, `tx_cut`, `rx_warn_flag`, `rx_cut_flag`, `tx_warn_flag`, `tx_cut_flag` | Submit form to update alert thresholds & set flags | +| `/network/wifi/usage/reset` | GET | | Reset the stored network data usage total to zero | +| `/shutdown` | GET | | Shutdown menu | + +## JSON API (`src/json_api.rs`) + +All JSON API calls are prefixed by `/api/v1/`. This has been excluded from the table below to keep the table compact. + +| Endpoint | Method | Parameters | Description | +| --- | --- | --- | --- | +| `device/reboot` | POST | | Reboot device | +| `device/shutdown` | POST | | Shutdown device | +| `network/activate_ap` | POST | | Activate WiFi access point mode | +| `network/activate_client` | POST | | Activate WiFi client mode | +| `network/ip` | GET | | Returns IP address values for wlan0 & ap0 interfaces | +| `network/rssi` | GET | | Returns RSSI for connected WiFi network | +| `network/ssid` | GET | | Returns SSID for connected WiFi network | +| `network/state` | GET | | Returns state of wlan0 & ap0 interfaces | +| `network/status` | GET | | Returns status object for connected WiFi network | +| `network/wifi` | GET | | Returns scan results for in-range access-points | +| `network/wifi` | POST | `ssid` & `pass` | Submit SSID & password to create new WiFi connection | +| `network/wifi/connect` | POST | `ssid` | Submit SSID to connect to a given WiFi network | +| `network/wifi/disconnect` | POST | `ssid` | Disconnect from the currently associated WiFi network | +| `network/wifi/forget` | POST | `ssid` | Submit SSID to delete credentials for given WiFi network | +| `network/wifi/modify` | POST | `ssid` & `pass` | Submit SSID & password to update the credentials for given WiFi network | +| `/network/wifi/usage` | POST | `rx_warn`, `rx_cut`, `tx_warn`, `tx_cut`, `rx_warn_flag`, `rx_cut_flag`, `tx_warn_flag`, `tx_cut_flag` | Submit form to update alert thresholds & set flags | +| `/network/wifi/usage/reset` | POST | | Reset network data usage total | +| `ping` | GET | | Returns `pong!` if `peach-web` is running | +| `ping/network` | GET | | Returns `pong!` if `peach-network` microservice is running | +| `ping/oled` | GET | | Returns `pong!` if `peach-oled` microservice is running | +| `ping/stats` | GET | | Returns `pong!` if `peach-stats` microservice is running | + +## Environment The web application deployment mode is configured with the `ROCKET_ENV` environment variable: @@ -77,7 +131,7 @@ Logging is made available with `env_logger`: Other logging levels include `debug`, `warn` and `error`. -### Setup +## Setup Clone this repo: @@ -98,4 +152,38 @@ Run the binary: _Note: Networking functionality requires peach-network microservice to be running._ +## Debian Packaging +A `systemd` service file and Debian maintainer scripts are included in the `debian` directory, allowing `peach-web` to be easily bundled as a Debian package (`.deb`). The `cargo-deb` [crate](https://crates.io/crates/cargo-deb) can be used to achieve this. + +Install `cargo-deb`: + +`cargo install cargo-deb` + +Move into the repo: + +`cd peach-web` + +Build the package: + +`cargo deb` + +The output will be written to `target/debian/peach-web_0.3.0_arm64.deb` (or similar). + +Install the package as follows: + +`sudo dpkg -i target/debian/peach-web_0.3.0_arm64.deb` + +The service will be automatically enabled and started. + +Uninstall the service: + +`sudo apt-get remove peach-web` + +Remove configuration files (not removed with `apt-get remove`): + +`sudo apt-get purge peach-web` + +## Licensing + +AGPL-3.0