mirror of
https://github.com/MarekWo/mc-webui.git
synced 2026-07-30 05:23:21 +02:00
feat(android): ship the Android companion app with an install guide
A thin WebView wrapper that opens a user's own mc-webui instance full screen, without the browser address bar. It asks once for the server address and remembers it; all logic stays on the server. - android/mc-webui-wrapper.apk (1.0, it.wojtaszek.mc.wrapper, minSdk 21) - docs/android-app.md: download + checksum, "unknown sources" permission, the Play Protect notice, first connection, and the limitations that come with a WebView (no notifications, no QR camera, no file downloads) - README, user guide and whatsnew entries, incl. an app-vs-PWA comparison - *.apk marked binary so the text=auto rule can never touch it Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
MarekWo
@@ -1,2 +1,3 @@
|
||||
* text=auto
|
||||
*.sh text eol=lf
|
||||
*.apk binary
|
||||
|
||||
@@ -38,6 +38,7 @@ A lightweight web interface providing browser-based access to MeshCore mesh netw
|
||||
- **DM delivery tracking** - ACK-based delivery confirmation with SNR, route, and hop count details
|
||||
- **Multi-device support** - Database file named after device public key for easy multi-device setups
|
||||
- **PWA support** - Browser notifications and installable app (experimental)
|
||||
- **Android app** - Optional companion app that opens your instance full screen, without the browser address bar
|
||||
- **Full offline support** - Works without internet (local Bootstrap, icons, emoji picker)
|
||||
|
||||
For detailed feature documentation, see the [User Guide](docs/user-guide.md).
|
||||
@@ -285,6 +286,21 @@ For complete usage instructions, see the [User Guide](docs/user-guide.md).
|
||||
|
||||
---
|
||||
|
||||
## Android App
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="200" align="center"><a href="images/android-wrapper-setup.jpg"><img src="images/android-wrapper-setup.jpg" width="180"></a></td>
|
||||
<td>
|
||||
A companion app that opens your own instance full screen — no address bar, its own icon in the app drawer. Everything still runs on your server; the app only displays it.<br><br>
|
||||
It is not distributed through Google Play. Download <a href="android/mc-webui-wrapper.apk"><code>android/mc-webui-wrapper.apk</code></a>, install it on the phone, and enter the address of your instance once (e.g. <code>http://192.168.1.100:5000</code>).<br><br>
|
||||
Full instructions — including the "unknown sources" and Play Protect warnings, and what the app can and cannot do — are in the <a href="docs/android-app.md">Android App guide</a>.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## Updating
|
||||
|
||||
### Docker Hub installation
|
||||
@@ -444,6 +460,7 @@ sudo ~/mc-webui/scripts/updater/install.sh --uninstall
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [User Guide](docs/user-guide.md) | Complete feature documentation |
|
||||
| [Android App](docs/android-app.md) | Installing the Android companion app and connecting it to your instance |
|
||||
| [Architecture](docs/architecture.md) | Technical details, API reference |
|
||||
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
|
||||
| [Docker Installation](docs/docker-install.md) | How to install Docker on Debian/Ubuntu |
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,171 @@
|
||||
# mc-webui for Android
|
||||
|
||||
A small companion app that opens **your own** mc-webui instance full screen — no
|
||||
address bar, no browser tabs, its own icon in the app drawer. It looks and works
|
||||
like a native app, because underneath it is the same web interface you already
|
||||
use in the browser.
|
||||
|
||||
The app contains no mesh logic of its own: it asks once for the address of your
|
||||
mc-webui server and displays it. Everything still runs on your server and your
|
||||
MeshCore device.
|
||||
|
||||
The app is **not distributed through Google Play** — you download the `.apk`
|
||||
file from this repository and install it yourself. That is a normal and
|
||||
supported way to install Android apps, but Android will warn you a few times
|
||||
along the way. The steps below cover those warnings.
|
||||
|
||||
---
|
||||
|
||||
## What you need
|
||||
|
||||
- **Android 5.0 (Lollipop) or newer**
|
||||
- A running **mc-webui** instance the phone can reach — either on the same local
|
||||
network (e.g. `http://192.168.1.100:5000`) or published over the internet
|
||||
through a reverse proxy (e.g. `https://mc-webui.example.com`)
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Download the app
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| **File** | [`android/mc-webui-wrapper.apk`](../android/mc-webui-wrapper.apk) |
|
||||
| **Direct link** | https://github.com/MarekWo/mc-webui/raw/main/android/mc-webui-wrapper.apk |
|
||||
| **Size** | 5.7 MB |
|
||||
| **App version** | 1.0 |
|
||||
| **Package** | `it.wojtaszek.mc.wrapper` |
|
||||
| **SHA-256** | `12e1e388e01a68e0de73672808033a2ff8417df7075a229e3be9eccc6f7ff82c` |
|
||||
|
||||
Download it directly on the phone, or copy it over from a computer.
|
||||
|
||||
**Optional — verify the file.** Only worth doing if you got the file from
|
||||
somewhere other than this repository:
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
sha256sum mc-webui-wrapper.apk
|
||||
|
||||
# Windows (PowerShell)
|
||||
Get-FileHash mc-webui-wrapper.apk -Algorithm SHA256
|
||||
```
|
||||
|
||||
The result must match the SHA-256 above.
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Allow installation from unknown sources
|
||||
|
||||
Android only installs apps from Google Play unless you allow the app that is
|
||||
doing the installing — usually your browser or the Files app — to install
|
||||
others. You grant that permission once, and it applies to that app only.
|
||||
|
||||
**The easy way** — just start the installation (Step 3). When Android says
|
||||
*"For your security, your phone is not allowed to install unknown apps from
|
||||
this source"*, tap **Settings**, turn on **Allow from this source**, and press
|
||||
back. The installation continues.
|
||||
|
||||
**Up front, if you prefer** — Settings → **Apps** → **Special app access** →
|
||||
**Install unknown apps** → pick the browser or file manager you will use →
|
||||
**Allow from this source**. The exact wording varies by manufacturer (Samsung,
|
||||
Xiaomi, and others each name it slightly differently).
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Install
|
||||
|
||||
1. Open the downloaded `mc-webui-wrapper.apk` — from the browser's download
|
||||
notification, or from **Files → Downloads**
|
||||
2. Tap **Install**
|
||||
3. **Play Protect** may show *"Unsafe app blocked"* or *"App scan
|
||||
recommended"*. This is Google's standard notice for apps that did not come
|
||||
from the Play Store — it is not a detection of anything in the app. Choose
|
||||
**More details → Install anyway** (or **Don't send / Install** if it offers
|
||||
to upload the file for scanning)
|
||||
4. Tap **Open**, or launch **mc-webui** from the app drawer
|
||||
|
||||
To remove it later: long-press the icon → **Uninstall**, like any other app.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Connect to your instance
|
||||
|
||||
On the first run the app asks for the address of your server:
|
||||
|
||||
<p align="center">
|
||||
<img src="../images/android-wrapper-setup.jpg" width="300" alt="mc-webui Android app - server address screen">
|
||||
</p>
|
||||
|
||||
Type the full address, including the protocol and — for a local instance — the
|
||||
port:
|
||||
|
||||
| Your setup | What to enter |
|
||||
|---|---|
|
||||
| mc-webui on the local network | `http://192.168.1.100:5000` |
|
||||
| Behind a reverse proxy with a certificate | `https://mc-webui.example.com` |
|
||||
| On a non-standard port behind a proxy | `https://mc-webui.example.com:8443` |
|
||||
|
||||
Then tap **SAVE & CONNECT**.
|
||||
|
||||
> **Type `http://` explicitly for local instances.** If you leave the protocol
|
||||
> out, the app assumes `https://` and the connection to a plain local server
|
||||
> will fail.
|
||||
|
||||
The address is remembered, so every later launch goes straight into mc-webui.
|
||||
|
||||
### Changing the address later
|
||||
|
||||
The app returns to the address screen when you press **Back** on the main
|
||||
mc-webui page, and also when it cannot reach the server (wrong address, server
|
||||
down, phone off the network). Enter the address again — corrected if it was
|
||||
wrong, unchanged if the server was simply unreachable — and tap **SAVE &
|
||||
CONNECT**.
|
||||
|
||||
---
|
||||
|
||||
## What works, and what doesn't
|
||||
|
||||
Everything you do in mc-webui itself works exactly as in the browser: channels,
|
||||
direct messages, contacts, the console, My Repeaters, the Path Analyzer, maps,
|
||||
settings, themes. A few things live outside the page and are not wired up in
|
||||
this version of the wrapper:
|
||||
|
||||
| Feature | In the app | Instead |
|
||||
|---|---|---|
|
||||
| **Notifications** for new messages | Not available — the app has no access to the browser notification system | Install mc-webui as a **PWA** in Chrome for notifications ([how](user-guide.md#installing-as-pwa)); the two can live side by side |
|
||||
| **Scanning a QR code** (Add Contact → Scan QR) | Not available — the app does not request camera access | **Paste URI** or **Manual entry** on the same screen |
|
||||
| **Downloading files** (database backup, saving a QR image) | Does nothing when tapped | Do it from a browser on the phone or from a computer |
|
||||
| **HTTPS with a self-signed certificate** | Refused, with an "SSL Error" message | Use a valid certificate (e.g. Let's Encrypt), or plain `http://` on the local network |
|
||||
|
||||
---
|
||||
|
||||
## Security notes
|
||||
|
||||
- **Install the `.apk` only from this repository** (or from the project's
|
||||
GitHub Releases page). An `.apk` from anywhere else is a different app, no
|
||||
matter what it is called
|
||||
- The app stores exactly one thing on the phone: **the server address you
|
||||
typed**. No messages, keys, or contacts — those stay on your server and your
|
||||
MeshCore device
|
||||
- **Plain `http://` is allowed** so that local instances work without a
|
||||
certificate. On a home network that is fine; over the internet, put mc-webui
|
||||
behind a reverse proxy with HTTPS and some form of access control — the app
|
||||
adds no authentication of its own
|
||||
- The app requests a single Android permission: **internet access**
|
||||
|
||||
---
|
||||
|
||||
## How it is built
|
||||
|
||||
A minimal Android WebView wrapper: one screen for the server address, one
|
||||
full-screen WebView for mc-webui itself, and a saved preference between them.
|
||||
No analytics, no third-party services, no background activity — when the app is
|
||||
closed, nothing of it runs.
|
||||
|
||||
---
|
||||
|
||||
## See also
|
||||
|
||||
- [User Guide](user-guide.md) — everything the interface itself can do
|
||||
- [PWA Notifications](user-guide.md#pwa-notifications) — the browser-based
|
||||
alternative, with notification support
|
||||
- [Troubleshooting](troubleshooting.md) — when the server itself misbehaves
|
||||
@@ -26,6 +26,7 @@ This guide covers all features and functionality of mc-webui. For installation i
|
||||
- [Network Commands](#network-commands)
|
||||
- [PWA Notifications](#pwa-notifications)
|
||||
- [Notifications Tab](#notifications-tab)
|
||||
- [Android App](#android-app)
|
||||
|
||||
---
|
||||
|
||||
@@ -1055,6 +1056,35 @@ To get the full PWA experience with app badge counters:
|
||||
|
||||
---
|
||||
|
||||
## Android App
|
||||
|
||||
Besides installing mc-webui as a PWA, there is a small **Android companion
|
||||
app** that opens your instance full screen — no address bar, its own icon in
|
||||
the app drawer. It contains no mesh logic: it asks once for the address of your
|
||||
server (e.g. `http://192.168.1.100:5000`) and displays it, so everything still
|
||||
runs on your server and your MeshCore device.
|
||||
|
||||
<p align="center">
|
||||
<img src="../images/android-wrapper-setup.jpg" width="280" alt="mc-webui Android app - server address screen">
|
||||
</p>
|
||||
|
||||
The app is not distributed through Google Play — you download the `.apk` from
|
||||
the repository and install it yourself, which means going past a couple of
|
||||
Android warnings. The **[Android App guide](android-app.md)** walks through the
|
||||
download, the "unknown sources" permission, the Play Protect notice, and the
|
||||
first connection.
|
||||
|
||||
**App or PWA?** They can coexist, and each is better at something:
|
||||
|
||||
| | Android app | PWA (Chrome → Add to Home Screen) |
|
||||
|---|---|---|
|
||||
| Full screen, own icon | Yes | Yes |
|
||||
| Setup | Install `.apk`, type the address once | Open in Chrome, add to home screen |
|
||||
| Notifications | Not available | Available (see above) |
|
||||
| QR scanning, file downloads | Not available | Available |
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **What's New:** [whatsnew.md](whatsnew.md)
|
||||
|
||||
+3
-1
@@ -10,7 +10,9 @@ For deep technical notes, see [architecture.md](architecture.md). For the full g
|
||||
|
||||
## Unreleased
|
||||
|
||||
_Nothing yet since 2.2.0._
|
||||
### New features
|
||||
|
||||
- **There is an Android app now.** A small companion app opens your own instance full screen — no address bar, its own icon in the app drawer, and it looks like a proper Android app rather than a page in a browser. It holds no mesh logic of its own: on first run it asks for the address of your server (`http://192.168.1.100:5000` on the local network, or your `https://` hostname behind a reverse proxy), remembers it, and from then on launches straight into mc-webui. Everything still runs on your server and your MeshCore device. It is not on Google Play, so you download the `.apk` from the repository and install it yourself — the new [Android App guide](android-app.md) walks through that, including the "unknown sources" permission and the Play Protect notice Android shows for any app that didn't come from the Play Store. Two things still belong to the browser: notifications and QR scanning, so if you rely on those, keep the Chrome "Add to Home Screen" install — the two can live side by side.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 121 KiB |
Reference in New Issue
Block a user