Mark Joshwel c6eadc6045 docs: add mkdocs site :O

2024-06-18 18:59:55 +08:00

10 KiB

Raw Permalink Blame History

surplus on wheels (s+ow)

surplus on wheels is a pure shell script to get your location using termux-location, process it through surplus, and send it to messaging service or wherever using “bridges”

surplus was made to emulate sending your location through the iOS Shortcuts app, and surplus on wheels complements it by running surplus automatically using a cron job. (but using it manually also works!)

installing

!!! important
s+ow is a Termux-first script, and will not work anywhere else unless you have a utility that emulates termux-location on $PATH alongside bridges that supports your platform

there are two notable ways to install s+ow:

as a standalone script
or, as a cron job

there is also an installation script for quickly getting started from a fresh termux installation

as a standalone script

firstly install python and termux-api if you haven't already:
```
pkg install python termux-api
```
also install the accompanying Termux:API app from F-Froid
install pipx if you haven't already:
```
pip install pipx
```
install surplus:
```
pipx install surplus
```

install surplus on wheels:

mkdir -p ~/.local/bin/
wget  -O ~/.local/bin/s+ow https://surplus.joshwel.co/spow.sh
chmod +x ~/.local/bin/s+ow

!!! note if wget throws a 404, see backup links

if ~/.local/bin is not in your $PATH, add the following to your shell's rc file:

export PATH="$HOME/.local/bin:$PATH"

et voilà! s+ow is now setup. to actually send the message to a messaging platform, install an appropriate bridge

as a cron job

!!! important
these instructions rely on following the previous instructions

install necessary packages to run cron jobs:
```
pkg install cronie termux-services
```
restart termux and start the cron service:
```
sv-enable cron
```
set up the cron job:

run the following command:
```
crontab -e
```
and add the following text:
```
59 * * * *      bash -l -c "(SPOW_TARGETS="" SPOW_CRON=y s+ow)"
```
!!! important minimally fill in the SPOW_TARGETS variable before running s+ow. (see usage for more info)

this will run s+ow every hour, a minute before the hour

modify the variables as per your needs. see usage for more information

et voilà! s+ow will now send a message every hour. feel free to experiment with the cron job to your liking. see crontab.guru if you’re new to cron jobs

if you haven’t already, install an appropriate bridge to actually send a message to a messaging platform

using installation scripts

!!! warning these scripts assume you're starting from a fresh base installation of Termux. if you have already cron jobs, then manually carry out the instructions in 'as a cron job'

!!! important if not installed already, install Termux:API from F-Droid, not the Play Store

setup s+ow:
```
wget -O- https://surplus.joshwel.co/termux.sh | sh
```
!!! note if wget throws a 404, see backup links
restart termux!
and finally, set up a cron job from step 3 onwards ('set up the cron job')

usage

environment variables

s+ow's behaviour can be customised environment variables, with SURPLUS_CMD being the only required variable:

SPOW_TARGETS
a single line of comma-delimited chat IDs with bridge prefixes
```
wa:000000000000000000@g.us,tg:-0000000000000000000,...
```
in the example above, the WhatsApp chat ID is wa:-prefixed as recognised by the spow-whatsapp-bridge, and the Telegram chat ID is tg:-prefixed as recognised by the spow-telegram-bridge
SPOW_CRON (optional)
set as non-empty to declare that s+ow is being run as a cron job

if running as a cron job, start s+ow one minute earlier than intended to account for the time it takes to run termux-location and surplus. s+ow assumes this and delays itself appropriately

setting it to n will also be treated as if it were empty
SPOW_PRIVATE (optional)
set as non-empty to discard all logs when s+ow is done:
- $HOME/.cache/s+ow/out.log will be set to /dev/null
- $HOME/.cache/s+ow/err.log will be set to /dev/null
- $HOME/.cache/s+ow/location.net.json will be cleared after use locating the device
- $HOME/.cache/s+ow/location.gps.json will be cleared after use locating the device
- $HOME/.cache/s+ow/location.json will be cleared after use locating the device
- $HOME/.cache/s+ow/surplus.out.log will be cleared after use generating the message
- $HOME/.cache/s+ow/surplus.err.log will be set to /dev/null
- $HOME/.cache/s+ow/message will be cleared after all bridges has sent the message
!!! warning the only file not cleared is s+ow's last successful message file, $HOME/.cache/s+ow/last, as s+ow uses this as the first fallback message if it couldn't locate the device in time. if you're fine with using the LOCATION_FALLBACK string, feel free to modify your cron job to remove this file after running s+ow

setting it to n will also be treated as if it were empty
SURPLUS_CMD (optional)
the custom invocation used when calling surplus, modify this if you want to add certain flags

this defaults to surplus -td

!!! warning when overriding, ensure you also have -td (--using-termux-location and --debug) in your custom invocation!
LOCATION_CMD (optional)
the custom invocation used when calling termux-location, modify this if you want to bodge together surplus on wheels on non-termux systems. see (emulating termux-location) for more information

this defaults to termux-location
LOCATION_PRIORITISE_NETWORK (optional)
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

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

setting it to n will also be treated as if it were empty
LOCATION_TIMEOUT (optional)
set as a number to override the default first location timeout of 50
LOCATION_FALLBACK (optional)
a string that can be formatted with three numbers using %d:
1. s+ow's status
2. number of location attempts before giving up
3. type of message sent
see details on notification numbers for the meanings of each number. 'a', 'b' and 'c' map to A, B and C

defaults to %d%d%d?

faking locations

sometimes you gotta do what you gotta do

you can fake your s+ow messages by either:

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 turn off location on your device
setting a fake file in s+ow cache

!!! warning
s+ow uses the read command to read the file. as such, it is possible for s+ow to prematurely stop reading the file if the file does not contain a trailing newline.

you can also write text to $HOME/.cache/s+ow/fake to fake upcoming messages. the file is delimited by empty lines. as such, arrange the file like so:
```
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

details on notification numbers

after each run, or if s+ow had to use a location fallback string, s+ow notifies you:

!!! abstract "surplus on wheels" Run has finished.

Singapore Conference Hall  
7 Shenton Way  
068809  
Central, Singapore

(A, B, C, D<E>)  
[lc:W sp:X sm:Y - Z]

!!! abstract "surplus on wheels has errored" (A, B, C, D)
[lc:W sp:X sm:Y - Z]

the top line denotes general statuses:

A: s+ow's status
- 0 is nominal
- 1 is a termux-location error
- 2 is a surplus error
- 3 is a bridge/message send error
B: number of location attempts before giving up
C: type of message sent
- 0 for freshly made sharetext
- 1 for recycling a previous successful location sharetext (last file)
- 2 for using fallback template
D: number of bridge failures
E: each bridge's return code

the bottom line details on how long s+ow spent on each stage:

W: time to locate
X: time to run surplus
Y: time to send message(s)
Z: total run time

help! a bridge isn't working!

cool. do the following:

log out and log back in and try again
if that didn't fix it, update/reinstall the bridge and try again
run the bridge's executable directly to see if there's any connection issues
look at your bridge's installation instructions to find out where it's located at. or, use the which command
if it connected successfully, or you see no errors, try typing in one of the targets you've set in SPOW_TARGETS for the bridge, and then press the enter/return key

!!! failure on the off chance you reinstalled the bridge, and it still failed either step 3 or 4, the bridge itself is faulty. file a bug report/issue with the bridge's project page or maintainer and tell them where it failed (was it connecting to the messaging service? or failure to send a message?)

10 KiB Raw Permalink Blame History Unescape Escape