{"id":15293191,"url":"https://github.com/ams-osram/osp_aoui32","last_synced_at":"2026-03-05T23:38:36.563Z","repository":{"id":257802717,"uuid":"852867761","full_name":"ams-OSRAM/OSP_aoui32","owner":"ams-OSRAM","description":"A library with drivers for the UI elements on the OSP32 board (the OSP/SAID root MCU board).","archived":false,"fork":false,"pushed_at":"2025-05-21T10:00:45.000Z","size":333,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-21T11:21:44.957Z","etag":null,"topics":["arduino","as1163","e3731i","library","osp","rgb-led"],"latest_commit_sha":null,"homepage":"https://github.com/ams-OSRAM/OSP_aotop","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ams-OSRAM.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"license.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-05T15:08:17.000Z","updated_at":"2025-05-21T10:00:22.000Z","dependencies_parsed_at":"2024-09-27T14:43:23.150Z","dependency_job_id":"e6e9ab60-7fdd-479e-905d-5d7c96b31903","html_url":"https://github.com/ams-OSRAM/OSP_aoui32","commit_stats":{"total_commits":5,"total_committers":1,"mean_commits":5.0,"dds":0.0,"last_synced_commit":"a6e0d8d6c784ea44ec12d67e9657f777a1e896b6"},"previous_names":["ams-osram/osp_aoui32"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/ams-OSRAM/OSP_aoui32","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ams-OSRAM%2FOSP_aoui32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ams-OSRAM%2FOSP_aoui32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ams-OSRAM%2FOSP_aoui32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ams-OSRAM%2FOSP_aoui32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ams-OSRAM","download_url":"https://codeload.github.com/ams-OSRAM/OSP_aoui32/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ams-OSRAM%2FOSP_aoui32/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265899815,"owners_count":23845875,"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":["arduino","as1163","e3731i","library","osp","rgb-led"],"created_at":"2024-09-30T16:44:57.118Z","updated_at":"2026-03-05T23:38:36.497Z","avatar_url":"https://github.com/ams-OSRAM.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OSP UIDriversOSP32 aoui32\n\nLibrary \"OSP UIDriversOSP32 aoui32\", usually abbreviated to \"aoui32\", \nis one of the **aolibs**; short for Arduino OSP libraries from ams-OSRAM.\nThis suite implements support for chips that use the Open System Protocol, \nlike the AS1163 (\"SAID\") or the OSIRE E3731i (\"RGBi\").\nThe landing page for the _aolibs_ is on \n[GitHub](https://github.com/ams-OSRAM/OSP_aotop).\n\n\n## Introduction\n\nLibrary _aoui32_ contains drivers for the UI elements on the OSP32 board. \nAs a result, library _aoui32_ does not depend on the other _aolibs_,\nonly on the Arduino API (GPIO pins and I2C). It can be used in isolation.\n\n![aoui32 in context](extras/aolibs-aoui32.drawio.png)\n\n\n### UI Elements \nThis library drives the following elements.\n\n - A, X, and Y button\n - red and green signaling LED\n - 128×32 OLED\n\nThe (OLED) display is intentionally small to only feedback a minimum of information.\nThe intention is that the screen shows the \"application state\":\n - Which app is running (its name);  the A button selects next app.\n - What the X and Y button do in the current app.\n\n![OLED showing state](extras/state.jpg)\n\n\n### Board\n\nThe image below shows the OSP32 board with the UI elements highlighted in red.\n\n![OSP32 board with UI](extras/osp32ui.jpg)\n\n\n## Examples\n\nThis library comes with the following examples.\nYou can find them in the Arduino IDE via \nFile \u003e Examples \u003e OSP UIDriversOSP32 aoui32 \u003e ...\n\n- **aoui32_but** ([source](examples/aoui32_but))  \n  This demonstrates how to detect button presses and button releases of the\n  buttons on the OSP32 board. The library can report the transitions (events\n  like button _going_ down or _going_ up), not just the button _being_ down \n  or _being_ up.\n\n- **aoui32_led** ([source](examples/aoui32_led))  \n  This demo shows the various ways the signaling LEDs on the OSP32 board \n  can be controlled: on/off/toggle, changing a single or both LEDs.\n\n- **aoui32_oled** ([source](examples/aoui32_oled))  \n  This demo demonstrates the OLED on the OSP32 board. Button A controls the \n  OLED contents, and buttons X and Y control the green and red signaling LED. \n  This demo also has a splash screen.\n\n\n## Module architecture\n\nThis library contains three modules, see figure below (arrows indicate `#include`).\n\n![Modules](extras/aoui32-modules.drawio.png)\n\n- **aoui32_but** (`aoui32_but.cpp` and `aoui32_but.h`) is a small module that implements \n  functions to check for button (A, X, Y) _transitions_ (\"went down\").\n\n- **aoui32_led** (`aoui32_led.cpp` and `aoui32_led.h`) is a small module that implements \n  functions to switch one or more signaling LEDs (the red and/or the green one) \n  on or off (or toggle).\n\n- **aoui32_oled** (`aoui32_oled.cpp` and `aoui32_oled.h`) is a small module that implements \n  some wrapper functions on top of a library for an OLED display. The wrapper uses the \n  [Tiny OLED library](https://github.com/maarten-pennings/toled/) (toled).\n  The _aoui32_ library comes with a [copy](src/toled) of toled included, to ensure there\n  are no versioning issues. The included library is a single module (c/h file),\n  but it comes with 5 extra files, each implementing a font of some size.\n\n\n## API\n\nThe header [aoui32.h](src/aoui32.h) contains the API of this library.\nIt includes the module headers [aoui32_but.h](src/aoui32_but.h), [aoui32_led.h](src/aoui32_led.h), \nand [aoui32_oled.h](src/aoui32_oled.h).\nThe headers contain little documentation; for that see the module source files. \n\n\n### aoui32\n\n- `aoui32_init()` initializes the button and led pins and configures the OLED.\n- `AOUI32_VERSION`  identifies the version of the library.\n\n\n### aoui32_but\n\n- `aoui32_but_scan()` must be called regularly - see \"Execution architecture\".\n- `aoui32_but_isup(buts)` and `aoui32_but_isdown(buts)` check the current button state (a mask of buttons can be passed).\n- `aoui32_but_wentdown(buts)` and `aoui32_but_wentup(buts)` check button transitions (a mask of buttons can be passed).\n\n\n### aoui32_led\n\n- `aoui32_led_on(leds)`     switches all passed LEDs (mask) on.\n- `aoui32_led_off(leds)`    switches all passed LEDs (mask) off.\n- `aoui32_led_toggle(leds)` toggles all passed LEDs (mask).\n\n\n### aoui32_oled\n\n- `aoui32_oled_state(name,xlbl,ylbl)` shows a screen with three fields: \n  app name, function of X button, and function of Y button.\n \n  ![OLED showing state](extras/state.jpg)\n\n- `aoui32_oled_msg(msg)` shows a full screen (error) message in sans5 font.\n  There is also the variant `aoui32_oled_msgf(msg)` with printf like formatting.\n \n  ![OLED showing state](extras/message.jpg)\n\n- `aoui32_oled_splash(name,version)` shows a splash screen with name and version \n  of executable (and the OSP \"logo\").\n\n  ![OLED showing splash](extras/splash.jpg)\n\n- It should be noted that header \"aoui32.h\" includes \"toled.h\", so all low level primitives of the\n  underlying OLED driver (toled) are also available to an application using library _aoui32_.\n\n\n## Schematics\n\nThe _aoui32_ lib assumes a fixed wiring for the buttons (A, X, and Y), \nsignaling LEDs (red/error, green/ok), and the OLED. The OLED is assumed\nto be of resolution 128×32 pixels, and driven by an SSD1306 controller. \n\n![Wiring](extras/wiring.png)\n\n\n## Execution architecture\n\n\n### Buttons\n\nThe buttons require a regular call to `aoui32_but_scan()`. The module keeps the last two\nscan results (i.e. the button states), and with that it can determine a `aoui32_but_wentdown()` \nor `aoui32_but_wentup()` transition.\n\nCall `aoui32_but_scan()` frequently, say at least every 100ms, but preferably more often, for a smooth UI.\nTo prevent picking up contact bounce, too frequent calls are ignored (see constant `AOUI32_BUT_BOUNCE_MS`).\n\n\n### OLED\n\nThe OLED module keeps a 128×32 pixel monochrome frame buffer in which all draw operations take place.\nThe function `toled_clear()` erases the frame buffer. \nThe function `toled_commit()` sends the frame buffer, all 4096 pixels (512 bytes), \nover I2C to the OLED. The OLED has a 1MHz I2C connection, which one might hope \nresults in a transfer time of 128×32/1M = 4096 µs. In practice the transfer time is 6000 µs.\n\nDrawing a near full-screen rectangle on an ESP32S3 takes 45 µs (not even 1% of the transfer time), \nand drawing some text takes 340 µs (6% of the transfer time). These figures come from the\n[toled](https://github.com/maarten-pennings/toled/blob/main/example/toled-speed/toled-speed.ino)\nlibrary.\n\n| action           | time (µs) | % of transfer |\n|:-----------------|:---------:|:-------------:|\n| draw rectangle   |      45   |           1   |\n| draw text        |     340   |           6   |\n| transfer to OLED |    6000   |         100   |\n\n\n## Version history _aoui32_\n\n- **2025 May 25, 0.4.0**\n  - Added formatted message to OLED `aoui32_oled_msgf()`.\n  \n- **2025 March 3, 0.3.10**\n  - Improved doc on `aoui32_but_scan()`.\n  - Bug fix in `aoui32_but_init()`.\n  \n- **2024 November 29, 0.3.9**\n  - Text correction in `readme.md`.\n\n- **2024 October 8, 0.3.8**\n  - Prefixed `modules.drawio.png` with library short name.\n  - Moved domain from `github.com/ams-OSRAM-Group` to `github.com/ams-OSRAM`.\n  - BEHAVIOR added to examples.\n  \n- **2024 September 6, 0.3.7**\n  - Updated description in two examples.\n  - Updated `readme.md`.\n\n- **2024 September 5, 0.3.6**  \n  - Replaced OSP32 photo.\n  - API section in readme now shows parameter names.\n  - Added links in `readme.md` for all example sketches.\n  - Corrected link to GitHub from aotop to OSP_aotop.\n  - Remove \"oalib\" from `sentence=` in `library.properties`.\n  - Arduino name changed from `OSP Drivers UI OSP32 board - aoui32` to `OSP UIDriversOSP32 aoui32`.\n  - Renamed dir `extra` to `extras`.\n  - `license.txt`, `examples\\xxx.ino` line endings changed from LF to CR+LF.\n\n- **2024 July 02, 0.3.5**  \n  - Initial release candidate.\n\n\n(end)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fams-osram%2Fosp_aoui32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fams-osram%2Fosp_aoui32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fams-osram%2Fosp_aoui32/lists"}