https://github.com/ringtailsoftware/lyuba
ESP32 Mastodon Tooter
https://github.com/ringtailsoftware/lyuba
Last synced: 27 days ago
JSON representation
ESP32 Mastodon Tooter
- Host: GitHub
- URL: https://github.com/ringtailsoftware/lyuba
- Owner: ringtailsoftware
- License: mit
- Created: 2022-11-08T18:15:00.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2022-11-17T21:32:03.000Z (over 2 years ago)
- Last Synced: 2025-04-10T22:40:50.360Z (29 days ago)
- Language: C
- Size: 89.8 KB
- Stars: 34
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: MIT-LICENSE
Awesome Lists containing this project
README
# Lyuba ESP32 Mastodon Library
Arduino library for communicating with the Mastodon social network.
https://fosstodon.org/web/@lyuba
Toby Jaffey @[email protected]
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
1. Download the repository as a zip file
2. 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 ([email protected])
- `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
cJSON Copyright (c) 2009-2017 Dave Gamble and cJSON contributors