surplus/docs/onwheels/index.md

# surplus on wheels (s+ow)

surplus on wheels is a pure shell script to get your location using
[termux-location](https://wiki.termux.com/wiki/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](https://wiki.termux.com/wiki/termux-location)
    on `$PATH` alongside bridges that supports your platform

there are two notable ways to install s+ow:

1. [as a standalone script](#as-a-standalone-script)
2. or, [as a cron job](#as-a-cron-job)

there is also an [installation script](#using-installation-scripts) for quickly getting
started from a _fresh_ termux installation

### as a standalone script

1. firstly install python and termux-api if you haven't already:

    ```text
    pkg install python termux-api
    ```

    also install the accompanying Termux:API app from [F-Froid](https://f-droid.org/en/packages/com.termux.api/)

2. install pipx if you haven't already:

    ```text
    pip install pipx
    ```

3. install surplus:

    ```text
    pipx install surplus
    ```

4. install surplus on wheels:

    ```text
    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](../links.md)

    if `~/.local/bin` is not in your `$PATH`, add the following to your shell's rc file:
    
    ```shell
    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](bridges.md)

### as a cron job

!!! important  
    these instructions rely on following the [previous instructions](#as-a-standalone-script)

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. set up the cron job:

    run the following command:

    ```text
    crontab -e
    ```

    and add the following text:

    ```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)](#usage)

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

    modify the variables as per your needs.
    see [usage](#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](https://crontab.guru/) if you’re new to cron jobs

if you haven’t already, [install an appropriate bridge](bridges.md) 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](#as-a-cron-job)'

!!! important
    if not installed already, install
    [Termux:API from F-Droid](https://f-droid.org/en/packages/com.termux.api/), **not the Play Store**

1. setup s+ow:

    ```text
    wget -O- https://surplus.joshwel.co/termux.sh | sh
    ```

    !!! note
        if `wget` throws a 404, see [backup links](../links.md)

2. restart termux!

3. and finally, [set up a cron job](#as-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:

1. `SPOW_TARGETS`  
    a single line of comma-delimited chat IDs with bridge prefixes

    ```text
    wa:000000000000000000@g.us,tg:-0000000000000000000,...
    ```

    in the example above, the WhatsApp chat ID is `wa:`-prefixed as recognised by the
    [spow-whatsapp-bridge](whatsapp-bridge.md), and the
    Telegram chat ID is `tg:`-prefixed as recognised by the
    [spow-telegram-bridge](telegram-bridge.md)

2. `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

3. `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

4. `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!

5. `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`](emulating-termux-location.md)) for more information

    this defaults to `termux-location`

6. `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

7. `LOCATION_TIMEOUT` (optional)  
    set as a number to override the default first location timeout of `50`

8. `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](#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:

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 turn off location on your device

2. 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:

    ```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

### 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<E>)  
    [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:

1. log out and log back in and try again

2. if that didn't fix it, update/reinstall the bridge and try again

3. 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

4. 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?)