{"id":13771775,"url":"https://github.com/ringtailsoftware/lyuba","last_synced_at":"2025-04-12T16:35:11.325Z","repository":{"id":136877058,"uuid":"563491218","full_name":"ringtailsoftware/lyuba","owner":"ringtailsoftware","description":"ESP32 Mastodon Tooter","archived":false,"fork":false,"pushed_at":"2022-11-17T21:32:03.000Z","size":92,"stargazers_count":34,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-10T22:40:50.360Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ringtailsoftware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2022-11-08T18:15:00.000Z","updated_at":"2025-02-19T15:42:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"2e3c3332-6abb-4943-b0a5-63f86b07d35d","html_url":"https://github.com/ringtailsoftware/lyuba","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Flyuba","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Flyuba/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Flyuba/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ringtailsoftware%2Flyuba/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ringtailsoftware","download_url":"https://codeload.github.com/ringtailsoftware/lyuba/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248597073,"owners_count":21130804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T17:00:55.389Z","updated_at":"2025-04-12T16:35:11.289Z","avatar_url":"https://github.com/ringtailsoftware.png","language":"C","readme":"# Lyuba ESP32 Mastodon Library\n\nArduino library for communicating with the Mastodon social network.\n\nhttps://fosstodon.org/web/@lyuba\n\nToby Jaffey @tobyjaffey@mastodon.me.uk\n\nLyuba supports sending toots and polling for the most recent status matching a hashtag.\n\nAfter downloading, rename folder to 'lyuba' and install in Arduino Libraries folder. Restart Arduino IDE, then open `File-\u003eSketchbook-\u003eLibrary-\u003elyuba-\u003ehelloworld` sketch.\n\nCompatibility notes: ESP32 only (ESP32 variants should work but are untesed)\n\n## Installation\n\n 1. Download the repository as a zip file\n 2. In the Arduino IDE, navigate to Sketch -\u003e Include Library -\u003e Add .ZIP Library\n\n## Example sketches\n\n - `helloworld`, authenticate using username and password, send a single toot\n - `helloworld_token`, authenticate using an access token\n - `analogtoot`, authenticate using username and password, send a toot every 10s with an analog sensor reading\n - `publicstream`, authenticate using username and password, monitor public stream and print every toot\n - `cheerlights`, authenticate using username and password, monitor \"#cheerlights\" hashtag, parse colour name and show it on a single neopixel\n\n## Configuring sketches\n\nAll sketches must be setup for your WiFi network and Mastodon account. At the top of each sketch, update as follows:\n\n - `WIFI_SSID` your WiFi ssid\n - `WIFI_PASSWORD` your WiFi password\n - `MASTODON_USERNAME` your Mastodon username (username@domain.tld)\n - `MASTODON_PASSWORD` your Mastodon password\n - `MASTODON_HOST` the hostname of the Mastodon instance you use, e.g. \"fosstodon.org\" or \"mastodon.social\"\n\nIf 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\" -\u003e \"Development\" -\u003e \"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`.\n\n## Storage of access token\n\nThe `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()`.\n\n## API\n\nSee `lyuba.h` for the API prototypes.\n\nTo initialise the library, call:\n\n    lyuba_t *myLyuba = lyuba_init(const char *host, const char *username, const char *password);\n\n`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.\n\nIn your sketch's main loop, regularly call:\n\n    lyuba_loop(myLyuba);\n\nTo start the authentication process, call:\n\n    lyuba_authenticate(myLyuba, authCb);\n\nWhere `authCb` is a callback function. If `NULL` is used, authentication will occur but no callback will be made to the sketch:\n\n    void authCb(bool ok, const char *authToken) {}\n   \nOn successful authentication, `ok`=`true` and `authToken` will contain the authentication credentials. On failure `ok`=`false`\n\nTo read back a saved authentication token:\n\n    const char *authToken = lyuba_getAuthToken(myLyuba);\n\n`lyuba_getAuthToken()` will return NULL if no token as been setup. If this is the case, call `lyuba_authenticate()`.\n\nTo toot, call:\n\n    lyuba_toot(myLyuba, authToken, \"Hello World!\", tootCb);\n\nWhere `tootCb` is a callback function. If `NULL` is used, tooting will occur but no callback will be made to the sketch:\n\n    void tootCb(bool ok)\n\nOn successful tooting, `ok`=`true`. On failure `ok`=`false`\n\nTo stream all public toots, call:\n\n    lyuba_conn_t *myConn = lyuba_stream(myLyuba, authToken, \"public\", streamCb);\n\nTo stream a hashtag, call:\n\n    lyuba_conn_t *myConn = lyuba_stream(myLyuba, authToken, \"hashtag?tag=cheerlights\", streamCb);\n\nFor more details of available streams, see https://docs.joinmastodon.org/methods/timelines/streaming/\n\nWhere `streamCb` is a callback function which is passed each toot, pre-stripped of HTML tags:\n\n    void streamCb(bool ok, const char *username, const char *content) { }\n\nTo close a stream, call:\n\n    lyuba_close(myConn);\n\n## Notes\n\n - Lyuba should be considered insecure. Your Mastodon password is baked into your firmware unless token authentication is used\n - Lyuba is not thread safe, it expects to be used in an asynchronous manner by a single task\n - Running mulitple streams and requests concurrently is not well tested\n\n## License\n\nLyuba is MIT licensed\n\ncJSON Copyright (c) 2009-2017 Dave Gamble and cJSON contributors\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Embedded systems"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringtailsoftware%2Flyuba","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fringtailsoftware%2Flyuba","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fringtailsoftware%2Flyuba/lists"}