From 81cc317436d01b1587d1364535406d829853f93d Mon Sep 17 00:00:00 2001 From: Mark Joshwel Date: Sat, 28 Oct 2023 13:33:31 +0000 Subject: [PATCH] docs: add info on s+ow --- README.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 194 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7aa0b78..105b721 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ surplus is a Python script to convert to iOS Shortcuts-like shareable text. - [installation](#installation) + - [on Termux: surplus on wheels](#on-termux-surplus-on-wheels) - [usage](#usage) - [command-line usage](#command-line-usage) - [example api usage](#example-api-usage) @@ -51,6 +52,196 @@ feel free to grab that and embed it into your own program as you see fit. see [licence](#licence) for licensing information. +### on Termux: surplus on wheels + +surplus on wheels (s+ow) is a pure shell script to get your location using +`termux-location`, process it through surplus, and send it to a WhatsApp user/group using a +[modified mdtest demonstration binary from the tulir/whatsmeow project](https://github.com/markjoshwel/whatsmeow-termux/tree/main/mdtest). + +> [!IMPORTANT] +> if you just want to use surplus by itself, follow the normal installation guide above. + +there are two ways to install and setup s+ow: + +- [by itself](#by-itself) +- or [with an hourly cronjob](#with-an-hourly-cronjob) + +see [s+ow usage instructions here](#usi). + +#### by itself + +1. firstly install python and termux-api if you haven't already: + + ```text + pkg install python termux-api + ``` + + also install the accompanying the Termux:API app from the + [Play Store](https://play.google.com/store/apps/details?id=com.termux.api&hl=gl) or + [F-Froid](https://f-droid.org/en/packages/com.termux.api/). + +2. install surplus: + + ```text + pip install https://github.com/markjoshwel/surplus/releases/latest/download/surplus-latest-py3-none-any.whl + ``` + +3. install the modified mdtest binary for aarch64: + + ```text + wget https://github.com/markjoshwel/whatsmeow-termux/releases/latest/download/mdtest.tar.gz + tar -xvf mdtest.tar.gz + chmod +x mdtest + mkdir -p ~/.local/bin/ + mv mdtest ~/.local/bin/ + rm mdtest.tar.gz + ``` + +4. install surplus on wheels: + + ```text + mkdir -p ~/.local/bin/ + curl https://raw.githubusercontent.com/markjoshwel/surplus/main/s+ow > ~/.local/bin/s+ow + chmod +x ~/.local/bin/s+ow + ``` + +if `~/.local/bin` is not in your `$PATH`, add the following to your shell's rc file: + +```shell +export PATH="$HOME/.local/bin:$PATH" +``` + +#### with an hourly cronjob + +> [!IMPORTANT] +> these instructions rely on following the previous instructions, and assumes that s+ow works. + +1. install necessary packages to run cron jobs: + + ```text + pkg install cronie termux-services + ``` + +2. restart termux and start the cron service: + + ```text + sv-enable cron + ``` + +3. setup the cron job: + + > [!IMPORTANT] + > fill in the `JID_NOMINAL_TARGET` and `JID_ERRORED_TARGET` variables before running s+ow. + > [(see using s+ow)](#using-sow) + + run the following command: + + ```text + crontab -e + ``` + + and add the following text: + + ```text + 59 * * * * (sleep 30; JID_NOMINAL_TARGET="" JID_ERRORED_TARGET="" LOCATION_PRIORITISE_NETWORK=n SPOW_CRON=y ~/.local/bin/s+ow) + ``` + + this will run s+ow every hour, thirty seconds before a new hour. modify the variables + as per your needs. see [using s+ow](#using-sow) for more information. + +#### using s+ow + +for first-time setup of mdtest, run the following command and pair your WhatsApp account +with mdtest: + +```text +~/.local/bin/s+ow mdtest +``` + +s+ow uses two environment variables: + +1. `JID_NOMINAL_TARGET` + JID of the WhatsApp user/group to send the location to if everything runs correctly. + +2. `JID_ERRORED_TARGET` + JID of the WhatsApp user/group to send the stderr/logs to if something goes wrong. + +3. `SPOW_CRON` + set as non-empty to declare that s+ow is being run as a cron job. + cron jobs are run thirty seconds in advance to attempt to display surplus output + on time as waiting for a GPS lock may be slow. + +4. `LOCATION_PRIORITISE_NETWORK` + set as non-empty to declare that s+ow can just use network location instead of GPS + if GPS is taking too long. + you should only turn this on if punctuality means that much to you, or you’re in a + country with cell towers close by or everywhere, like Singapore. + + setting it to `n` will also be treated as empty. + +the JIDs can be obtained by sending a message to the user/group, while running +`s+ow mdtest`, and examining the output for your message. JIDs are email address-like +strings. + +you can fake your s+ow messages by either: + +1. setting a dummy `last` file in s+ow cache + + `$HOME/.cache/s+ow/last` is used as the fallback response when a part of s+ow (either + `termux-location` or `surplus` errors out). you can set this file to whatever you want + and just disable location permissions for Termux. + +2. setting a `fake` file in s+ow cache + + > [!IMPORTANT] + > this is currently unimplemented. + + you can also write text to `$HOME/.cache/s+ow/fake` to fake upcoming messages. the file + is delimited by two newlines. as such, arrange the file like so: + + ```text + The Clementi Mall + 3155 Commonwealth Avenue West + Westpeak Terrace + 129588 + Southwest, Singapore + + Westgate + 3 Gateway Drive + Jurong East + 608532 + Southwest, Singapore + + ... + ``` + + on every run of s+ow, the first group of lines will be consumed, and the file will be + updated with the remaining lines. if the file is empty, it will be deleted. + +#### quick install scripts + +> [!WARNING] +> these scripts assume you're starting from a fresh base install of Termux. +> if you have already cron jobs, then manually carry out the instructiions in +> [with an hourly cronjob](#with-an-hourly-cronjob). + +1. setup s+ow: + + ```text + curl https://raw.githubusercontent.com/markjoshwel/surplus/s+ow/termux-s+ow-setup | sh + ``` + +2. restart termux + +3. setup cron job: + + ```text + curl https://raw.githubusercontent.com/markjoshwel/surplus/s+ow/termux-s+ow-setup-cron | sh + ``` + +you can then run `crontab -e` to edit the variables as per your needs. +see [using s+ow](#using-sow) for more information. + ## usage ### command-line usage @@ -317,7 +508,7 @@ variables split_query -> ['Temasek', 'Polytechnic'] original_query -> 'Temasek Polytechnic' ``` - + ```text >>> surplus("77Q4+7X Austin, Texas, USA", surplus.Behaviour()) @@ -624,7 +815,7 @@ line breakdown of shareable text output, accompanied by their Nominatim keys: } ``` -- `SHAREABLE_TEXT_LINE_SETTINGS: dict[str, dict[int, tuple[str, bool]]]` +- `SHAREABLE_TEXT_LINE_SETTINGS: dict[str, dict[int, tuple[str, bool]]]` a dictionary of iso3166-2 country-portion string keys with a dictionary as their values @@ -650,7 +841,7 @@ line breakdown of shareable text output, accompanied by their Nominatim keys: ``` - `SHAREABLE_TEXT_NAMES: dict[str, tuple[str, ...]]` - + a dictionary of iso3166-2 country-portion string keys with a tuple of strings as their values a tuple of strings containing Nominatim keys used in shareable text line 0-2 and