Lyuba ESP32 Mastodon Library

Arduino library for communicating with the Mastodon social network.

Lyuba supports sending toots and polling for the most recent status matching a hashtag.

After downloading, rename folder to 'lyuba' and install in Arduino Libraries folder. Restart Arduino IDE, then open File->Sketchbook->Library->lyuba->helloworld sketch.

Compatibility notes: ESP32 only (ESP32 variants should work but are untesed)

Installation

Download the repository as a zip file
In the Arduino IDE, navigate to Sketch -> Include Library -> Add .ZIP Library

Example sketches

helloworld, authenticate using username and password, send a single toot
helloworld_token, authenticate using an access token
analogtoot, authenticate using username and password, send a toot every 10s with an analog sensor reading
publicstream, authenticate using username and password, monitor public stream and print every toot
cheerlights, authenticate using username and password, monitor "#cheerlights" hashtag, parse colour name and show it on a single neopixel

Configuring sketches

All sketches must be setup for your WiFi network and Mastodon account. At the top of each sketch, update as follows:

WIFI_SSID your WiFi ssid
WIFI_PASSWORD your WiFi password
MASTODON_USERNAME your Mastodon username (username@domain.tld)
MASTODON_PASSWORD your Mastodon password
MASTODON_HOST the hostname of the Mastodon instance you use, e.g. "fosstodon.org" or "mastodon.social"

If you are using token authentication instead of username and password, MASTODON_TOKEN should have the string "Bearer " followed by your token. To generate a token go to your Mastodon instance web site, click "Preferences" -> "Development" -> "New application". Give the application a name, everything else is optional. Click "Submit", then click on your new application in the list. Read off the "Your access token", prefix it with "Bearer " and place in MASTODON_TOKEN.

Storage of access token

The lyuba_auth() call sets Lyuba authentication up by registering an app with your Mastodon account. To avoid re-registering every time, the credentials (access token) are stored in the ESP32 flash using the Preferences module. After rebooting, the credentials can be retrieved and re-used with lyuba_getAuthToken().

API

See lyuba.h for the API prototypes.

To initialise the library, call:

lyuba_t *myLyuba = lyuba_init(const char *host, const char *username, const char *password);

host is the Mastodon server to connect to, username and password are the credentials and may be NULL if token authenticated is to be used. Returns a lyuba_t* which must be passed to other API calls.

In your sketch's main loop, regularly call:

lyuba_loop(myLyuba);

To start the authentication process, call:

lyuba_authenticate(myLyuba, authCb);

Where authCb is a callback function. If NULL is used, authentication will occur but no callback will be made to the sketch:

void authCb(bool ok, const char *authToken) {}

On successful authentication, ok=true and authToken will contain the authentication credentials. On failure ok=false

To read back a saved authentication token:

const char *authToken = lyuba_getAuthToken(myLyuba);

lyuba_getAuthToken() will return NULL if no token as been setup. If this is the case, call lyuba_authenticate().

To toot, call:

lyuba_toot(myLyuba, authToken, "Hello World!", tootCb);

Where tootCb is a callback function. If NULL is used, tooting will occur but no callback will be made to the sketch:

void tootCb(bool ok)

On successful tooting, ok=true. On failure ok=false

To stream all public toots, call:

lyuba_conn_t *myConn = lyuba_stream(myLyuba, authToken, "public", streamCb);

To stream a hashtag, call:

lyuba_conn_t *myConn = lyuba_stream(myLyuba, authToken, "hashtag?tag=cheerlights", streamCb);

For more details of available streams, see https://docs.joinmastodon.org/methods/timelines/streaming/

Where streamCb is a callback function which is passed each toot, pre-stripped of HTML tags:

void streamCb(bool ok, const char *username, const char *content) { }

To close a stream, call:

lyuba_close(myConn);

Notes

Lyuba should be considered insecure. Your Mastodon password is baked into your firmware unless token authentication is used
Lyuba is not thread safe, it expects to be used in an asynchronous manner by a single task
Running mulitple streams and requests concurrently is not well tested

License

Lyuba is MIT licensed

ringtailsoftware/lyuba