mileswwatkins / mouse

A chatbot to provide information to backcountry hikers via satellite SMS

Mouse 🐭

A chatbot to provide information to backcountry hikers via satellite SMS, such as on a Garmin InReach.

A note about safety

The backcountry can be dangerous, and Mouse is not a safety tool. You shouldn't depend on Mouse's information when making decisions, especially regarding hazardous weather or wildfires.

How do I get access to Mouse?

Mouse is currently in beta, so you'll need to ask the developer (Miles Watkins) for Mouse's phone number. Once you have that phone number, you can text it from your Garmin InReach or other SMS-capable device.

Please only use Mouse on your satellite communication device if you pay for a plan with unlimited text messages! Mouse's responses can be long (ie, multiple messages) and quickly eat up your plan otherwise.

What can I ask Mouse?

Weather forecasts

The user must be using a Garmin InReach with location sharing turned on, in which case there will be an inreachlink.com/####### automatically appended to each text message the user sends. This link can be used to determine your GPS location and thus fetch your weather forecast.

Your message

weather

Mouse's response

2-day forecast for 16 Miles W Lone Pine CA, elevation 10981 ft

Today: Areas of smoke. Partly sunny, high of 49. SSW wind 10-15 mph.

Tonight: Widespread haze before 11pm. Mostly cloudy, then gradually becoming mostly clear, low of 31. SSW wind around 5 mph.

Thu Night: A 20% chance of snow showers after 11pm.  Partly cloudy, low of 27. W wind 10-15 mph.

Thu: Widespread haze between noon and 3pm. Sunny, high of 48. SSW wind 5-10 mph increasing to 10-15 mph in the afternoon. Gusts of 25 mph.

Trail closures

"Closure" here includes any safety notices, detours, updates, or hazards posted by the trail authority. Currently only supports the Pacific Crest Trail.

Number of closures in each region of a trail

Your message

closures pct

Mouse's response

Closures by region: Southern California 5, Central California 0, Northern California 5, Oregon 1, Washington 3

List of closures in a specific region of a trail

Your message

closures pct northern california

Mouse's response

[1] Dec 20 2021 closure: Caldor Fire in the Lake Tahoe region

[2] Dec 14 2021 reopening: River Complex Fires and McCash Fire in Klamath National Forest

[3] Dec 10 2021 closure: Dixie Fire

[4] Jun 23 2021 warning: Private timberlandcampingclosures in Northern Californiadue to fire risk

[5] Dec 14 2021 warning: North Complex (Claremont-Bear Fire) near Quincy, CA

Details on a specific closure

The number refers to which closure item in the list you would like to access. Only the first paragraph of the closure notice is included.

Your message

closures pct northern california 3

Mouse's response

Updated 12/10 9:20 AM The Pacific Crest Trail is closed near Warner Valley Road in the southern part of Lassen National Park. The rest of the Dixie Fire closures have been lifted, but Lassen National Forest stated in their press release that a closure order may be reinstated once restoration work begins in spring 2022.

Wikipedia

You can fetch the first paragraph of any Wikipedia article. Note that searching for an ambiguous or overly broad term (eg, Smith) will not return useful results.

Your message

wikipedia pokemon

Mouse's response

Pokémon is a Japanese media franchise managed by The Pokémon Company, a company founded by Nintendo, Game Freak, and Creatures. The franchise was created by Satoshi Tajiri in 1996, and is centered on fictional creatures called "Pokémon". In Pokémon, humans, known as Pokémon Trainers, catch and train Pokémon to battle other Pokémon for sport. All media works within the franchise are set in the Pokémon universe. The English slogan for the franchise is "Gotta Catch ‘Em All!". There are currently 901 Pokémon species.

Development

This project runs on the serverless architecture of Twilio Functions.

Requirements

• Node 12
• npm install

And if you want to deploy instead of just running/testing locally, then also:

• A Twilio account and active phone number
• Populating a .env file or your shell environment with your Twilio ACCOUNT_SID and AUTH_TOKEN

Tests

• npm run test runs all unit tests
• npm run test-watch runs a daemon that runs tests for all files that have changed since your last Git commit
• npm run test-e2e runs the end-to-end tests, that make actual HTTP requests

This project also uses Husky to propagate pre-commit Git hooks. Any new commit will trigger the unit tests, and commits on the main branch will trigger the end-to-end tests as well.

Running locally

npm run start

Then, you should be able to make HTTP POST requests to http://localhost:3000/mouse, making sure to include your desired message in the Body property of your POST data, eg:

curl http://localhost:3000/mouse \
    --request POST \
    --data '{"Body":"closures pct"}' \
    --header "Content-Type: application/json"

<?xml version="1.0" encoding="UTF-8"?><Response><Message>Closures by region: Southern California 5, Central California 0, Northern California 5, Oregon 1, Washington 3</Message><Message>To get a list of all closures in a region, include that region's name in your text (eg, text `closures central california`)</Message></Response>%

Deploying

• npm run deploy, which will (assuming success) print Deployment Details, which includes Mouse's Twilio Function's URL (eg https://mouse-1234-dev.twil.io/mouse)
• In the Twilio web console, navigate to your phone number, scroll down to the Messaging section, and in the A MESSAGE COMES IN section set your Webhook field to Mouse's URL
  • You'll only need to edit this field once; all future npm run deploy commands will deploy Mouse to the same URL (since the service ID is saved in a gitignore'd .twiliodeployinfo file)

mouse's Issues

Get more-up-to-date PCTA closures data

It appears that the PCTA website, the only source for closure and hazard notices (not apparently republished on Twitter, etc), now has Cloudflare/hCAPTCHA anti-bot code.

I'm communicating with the PCTA tech lead to see if there's a better/another way to access this data, but for now I'm scraping the Google cache (usually ~24–48 hours old) for this information. A longer term solution could be a daily/hourly AWS Lambda using Puppeteer headless Chrome to try avoiding Cloudflare bot detection, or a paid service to get past the hCAPTCHA. Neither are particularly desirable paths; let's hope that the PCTA has an official solution.

Add e2e tests for error messages

There are plenty of error messages returned due to improper user input; we should confirm that those trigger when we anticipate.

Eg:

• Error: You must include your InReach location link in your text message
• Error: You must provide a trail name in your text message, eg mileage pct

Allow different names for the same region

Eg, these invocations should resolve the same:

• closures pct norcal and closures pct Northern California
• closures pct washington and closures pct wa

Add invocation for sports scores

This feels like a big quality-of-life feature for users. But it's also a big domain. Probably worth focusing on whichever professional sports have the bulk of their season during North American backpacking months, or perhaps whichever sports have their playoffs during that time.

Also unclear what the cost to serve up this data will be, which is worth investigating on whichever API we use.

Also also, will these scores be live, or just after-the-fact? Will it just be a box score, or will there be any prose attached to it?

Add invocation for "what trail mile am I at?"

Low priority since this is something most hikers will discern via FarOut instead but could be a good convenience tool, and the infrastructure (of determining mileage) could be hooked into other functionality, such as push notifications when closures or notices are nearby the hiker.

Add phone number whitelist

Twilio doesn't allow a blocklist or whitelist for SMS/MMS functionality, so the best we can do is not reply to any phone numbers that aren't on a pre-approved list. This list, for privacy's sake, could be stored on a password-protected AWS S3 bucket, or even just an S3 file that's public but has an unguessable path/URI. Either way, the credentials for acting this list would need to be stored on Twilio Functions as environment variable secrets.

Refactor the AT closures module

There's some DRYing to do, since all three invocation handlers access the same webpage and list items. Not imminently easy, but with some focus there's certainly a good way to simplify this module.

Add push notifications for new closures

High-priority closures could be transmitted to all hikers on a trail, all hikers in a specific state (or who've recently messaged from a neighboring state), or all hikers who are going in that direction (would need to maintain a user database indicating NOBO or SOBO and their most recent check-in)

Add invocation for air quality forecasts

Main blocker is that it's unclear which of the many air quality models are most accurate in the mountains. I tried reaching out to the team leads by phone and email but no luck there.

The New York Times uses HRRR ("Rapid Refresh") in their wildfire/smoke map, but it's unclear whether this is the most accurate model for non-urban areas.

After that, it'll be some work to determine how to get a specific point's air quality value from their KMZ downloads (where each layer is a forecast at a point in time). And this'll probably be too big of a download and too computationally expensive to run every single time it's requested; we'll probably need an AWS Lambda that performs the work once every day (once the model has published) and pre-processes the results for various points along the trail, storing it in a JSON for the Twilio Function to fetch.

Add Prettier linting/formatting on-commit

Using Husky or similar

Make readme more readable for users

If the README is going to be a product demo, then it needs to read more like user-facing documentation than a REST API spec. Maybe switch from text to screenshots?

Related and part of this task, maybe the dev docs should be moved to a separate document!

Set up CI to run unit tests

And run e2e tests whenever pushing to main locally (via Husky) and whenever creating a PR against main (via CI system).

Allow Wikipedia search to handle proper nouns that don't follow first-letter capitalization

Words with internal capitalization (eg, Robert MacNamara) will fail in the Wikipedia search most of the time. It doesn't appear that the Wikipedia/Wikimedia REST API offers a search functionality, but maybe the other Wikipedia/Wikimedia XML/JSON APIs do, in which case we could fall back to that one.

See further explanation for how our current search functionality works inline at https://github.com/mileswwatkins/Mouse/blob/main/functions/wikipedia.private.js#L7-L17

Support closure information for Appalachian Trail

https://appalachiantrail.org/trail-updates/

Upside: doesn't appear to be anti-bot technology on the website

Downside: no easy way to get count by state, and even for a single state sometimes there're enough that pagination of the list on their website is required

Refactor invocation functions so that they all have the same function signature

Right now, the invocations look like:

handleWeatherInvocation(inReachSlug, days, callback)
handleClosuresInvocation(invocation, callback)
handleWikipediaInvocation(invocation, callback)

As more invocations are added, having some consistency in the function signature would be valuable. Maybe something like handleFoobar(invocation, options, callback)?

Paginate messages that are longer than a single SMS

Some progress and inline documentation already exists in https://github.com/mileswwatkins/Mouse/blob/main/functions/utils.private.js

If a message is longer than the length of an SMS, modern smartphones just handle it like a single MMS. But Garmin InReach will break it up on its servers and send the message as multiple SMSs. Unfortunately, Garmin will break these up at the character level, and they may not be received in the correct order, eg:

oshi Tajiri in 1996, and is centered on fictional creatures called "Pokémon". In Pokémon, humans, known as Pokémon Trainers, catch and train Pokémon to battle o

ther Pokémon for sport. All media works within the franchise are set in the Pokémon universe. The English slogan for the franchise is "Gotta Catch ‘Em All!". Th

Pokémon is a Japanese media franchise managed by The Pokémon Company, a company founded by Nintendo, Game Freak, and Creatures. The franchise was created by Sat

ere are currently 901 Pokémon species.

So, paginating the message (at the word-break level) into several separate SMSs and labeling their order before sending to Garmin is highly desirable, so that even if they're received out of order they are still legible; something like:

(2) Satoshi Tajiri in 1996, and is centered on fictional creatures called "Pokémon". In Pokémon, humans, known as Pokémon Trainers, catch and train Pokémon to

(3) battle other Pokémon for sport. All media works within the franchise are set in the Pokémon universe. The English slogan for the franchise is "Gotta Catch

(1) Pokémon is a Japanese media franchise managed by The Pokémon Company, a company founded by Nintendo, Game Freak, and Creatures. The franchise was created by

(4) ‘Em All!". There are currently 901 Pokémon species.

Replace "closures" terminology

Because that name isn't inclusive of all the information (updates, warnings, etc).

Maybe with "update" or "notifications" (although the latter is sorta overloaded in UX meaning).