ezod / aistweet

Twitter snapshot bot for a Raspberry Pi RTL-SDR AIS ship tracking station.

aistweet, a Twitter photo bot for Raspberry Pi AIS tracking stations

aistweet tracks ships via AIS and takes their picture with a Raspberry Pi camera as they pass by.

Written for and powering the Detroit River Boat Tracker. Read about how it was made!

How To Build It

Things you will need:

• a Raspberry Pi
• a Raspberry Pi Camera Module
• a USB SDR dongle, such as Nooelec NESDR Smart v4
• a VHF antenna suitable for receiving AIS transmissions
• an Adafruit VEML7700 ambient light sensor module (optional)

Build and install rtl-ais, and configure it to stream UDP data to the host and port defined by the aistweet command line.

If you want to also upload your AIS data to other services online and have a locally-hosted interactive map, you can use AIS Dispatcher for Linux.

It is important to set the latitude, longitude, and direction of your camera accurately in order for the snapshot timing to work. The direction is measured in degrees clockwise from north of the camera's center axis.

Command Line

usage: aistweet.py [-h] [--host HOST] [--port PORT] [--db DB]
                   [--hashtags HASHTAGS [HASHTAGS ...]] [--tts]
                   latitude longitude

Raspberry Pi AIS tracker/camera Twitter bot

positional arguments:
  latitude              AIS station latitude
  longitude             AIS station longitude
  direction             bearing of camera (degrees clockwise from north)

optional arguments:
  -h, --help            show this help message and exit
  --host HOST           host for receiving UDP AIS messages
  --port PORT           port for receiving UDP AIS messages
  --db DB               database file for static ship data
  --hashtags HASHTAGS [HASHTAGS ...]
                        hashtags to add to tweets
  --tts                 announce ship name via text-to-speech
  --light               disable night snapshots via light sensor

required environment variables:
  TWITTER_CONSUMER_API_KEY
  TWITTER_CONSUMER_API_KEY_SECRET
  TWITTER_ACCESS_TOKEN
  TWITTER_ACCESS_TOKEN_SECRET
  TWITTER_CLIENT_ID
  TWITTER_CLIENT_SECRET
  TWITTER_CALLBACK_URI

How To Authenticate With Twitter

Follow the instructions on the tweeter-basic repository to:

• create a Twitter v2 API project
• generate the required keys to be set as environment variables
  • note: the callback URI is recommended to be http://localhost/callback
• generate the required token by doing a 1-time self-hosted browser authentication
  • note: the token is auto-refreshed with every tweet. However, if the token isn't refreshed in 6 months it will require user intervention to be re-generated.

Dependencies

• astral
• emoji-country-flag
• event-scheduler
• geopy
• mpg321
• picamera
• pyais
• pytz
• timezonefinder
• tweeter-basic
• adafruit-circuitpython-veml7700 (optional)
• gTTS (optional)

aistweet's Issues

Some vessels generate multiple tweets

Occasionally, a vessel will generate multiple tweets (usually 2-3), with one "correct" photo and the others off-center or empty frame. The scheduler event is keyed by MMSI, and should be unique until 60 seconds after the tweet.

Protect ships dict completely with mutex

The ShipTracker.ships dictionary can change size during iteration if accessed directly (without the lock). Protect it completely with the mutex.

Scheduler breaks when multiple ships are in schedule

The tweet scheduler breaks when multiple ships are in the schedule simultaneously. This seems to be a bug in phluentmed/event-scheduler, which can be reproduced by scheduling (and maintaining references to) two separate future events, and then canceling one of them.

Clear ships from snap schedule after a short delay

Improve night photos

Currently the auto settings on the Pi camera are used for both day and night captures. Night photos are difficult to make out as a result. Use the sunset time based on latitude via astral to switch the camera to better settings for night photos.

Complete geometry tests

Write complete tests for the functions in the geometry module.

Broken with new Twitter API restrictions

The new Twitter API restrictions on the free tier appear to break the existing workflow for authentication.

Choose image crop based on vessel size in camera FOV

The current crop criterion is based only on vessel length and does not account for proximity to the camera, projection onto the camera plane, or the actual camera field of view. This often results in inappropriately cropped images.

Retry tweet on error

Currently, if an error is generated when tweeting, it is simply logged. These errors are almost always intermittent issues (e.g. over capacity). Add limited retry logic to avoid missing tweets.