{"id":15056371,"url":"https://github.com/esl/c3card","last_synced_at":"2025-04-10T04:07:41.525Z","repository":{"id":216589367,"uuid":"733492866","full_name":"esl/c3card","owner":"esl","description":"A workshop at CodeBEAM America 2024 showcasing custom hardware and Erlang-based firmware development using AtomVM.","archived":false,"fork":false,"pushed_at":"2024-11-18T16:42:41.000Z","size":1378,"stargazers_count":13,"open_issues_count":0,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-10T04:07:35.577Z","etag":null,"topics":["atomvm","erlang","esp32"],"latest_commit_sha":null,"homepage":"https://esl.github.io/c3card/","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2023-12-19T12:59:25.000Z","updated_at":"2025-04-04T02:14:02.000Z","dependencies_parsed_at":"2024-01-21T19:44:47.638Z","dependency_job_id":"62bfd3d6-c5f5-4ce8-8432-26190c706da2","html_url":"https://github.com/esl/c3card","commit_stats":null,"previous_names":["esl/c3card"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esl%2Fc3card","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esl%2Fc3card/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esl%2Fc3card/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esl%2Fc3card/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esl","download_url":"https://codeload.github.com/esl/c3card/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248154986,"owners_count":21056543,"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":["atomvm","erlang","esp32"],"created_at":"2024-09-24T21:50:10.199Z","updated_at":"2025-04-10T04:07:41.504Z","avatar_url":"https://github.com/esl.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C3Card\n\n[![Erlang/OTP Version](https://img.shields.io/badge/erlang%2Fotp-%2026-blue)](http://www.erlang.org)\n[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://esl.github.io/c3card/)\n[![Latest release](https://img.shields.io/github/v/release/esl/c3card)](https://github.com/esl/c3card/releases)\n\n![c3card](/images/c3card.jpg)\n\nA workshop at [CodeBEAM America 2024](https://codebeamamerica.com/)\nshowcasing custom hardware and Erlang-based firmware development.\n\n## Table of Contents\n\n  - [Introduction](#introdution)\n  - [Hardware](#hardware)\n  - [Firmware Overview](#firmware-overview)\n  - [Getting Started](#getting-started)\n  - [References](#references)\n  - [Contributing](#contributing)\n  - [License](#license)\n  - [Acknowledgements](#acknowledgements)\n\n## Introduction\n\nThis project is an exploration into custom hardware design and\nmanufacturing, and modern firmware development using AtomVM and the\nErlang ecosystem. It is meant to serve as a workshop for the upcoming\n[CodeBEAM America 2024](https://codebeamamerica.com/).\n\nCentral to the design is the ESP32C3 microcontroller, chosen for it's\nRISC-V and WiFi capabilities, as well as it's versatility and full\ncompatibility with AtomVM.\n\nThere is also a Neopixel LED array for it's programmable RGB\ncapabilities, allowing for a wide range of visual outputs. An AHT20\nsensor for cheap, low-powered and high-precision temperature\nreadings. An SSD1306 OLED display as an effective solution for\nreal-time data display, offering a 128x64 pixel resolution.\n\nAnd the last stellar feature of this project is the use of AtomVM, a\nnew implementation of the BEAM targetted at microcontrollers and\nembedded systems. This choice is driven by the desire to leverage all\nof the Erlang capabilities and robust features when it comes to\nconcurrency and fault-tolerant designs in a resource-constrained\nenvironment such as the ESP32.\n\n## Hardware\n\nThe overall list of components is the following:\n\n  - SSD1306 OLED display\n  - 4 buttons\n  - WS2812 Neopixel LED array\n  - AHT20 sensor\n  - 1 I2C Qwiic connector\n\nAnd the default IO pinouts are mapped as:\n\n  - IO0: Vbattery sense\n  - IO1: Charging flag\n  - IO2: I2C SDA\n  - IO3: I2C SCL\n  - IO4: WS2812 LED\n  - IO5: Button 1\n  - IO9: Button 2\n  - IO7: Button 3\n  - IO8: Button 4\n  - IO10: OLED Reset\n\n## Firmware Overview\n\nAs mentioned before, we are going to implement the application using\nErlang and leveraging the AtomVM BEAM implementation.\n\nThe application resembles a regular OTP application structure with\nsome caveats to take into consideration.\n\n### Dependencies\n\n  - ESP IDF v5.x for compiling AtomVM for the target device\n  - rebar3 is used for compiling the application, packing the .beam\n    files and flashing the device\n  - Erlang/OTP equal or higher than 25\n\n### Installing the AtomVM image\n\nBefore installing the application we need to flash AtomVM to the C3\ncard in order to have a starting image that can run the BEAM files.\n\nYou can follow the instructions at the [AtomVM getting started\nguide](https://www.atomvm.net/doc/master/getting-started-guide.html).\n\nIf you are compiling AtomVM from scratch, you need to compile a couple\nof extra components that are not included by default:\n\n  - [Neopixel driver](https://github.com/atomvm/atomvm_neopixel)\n\n## Getting Started\n\n### Building the firmware\n\nTo fetch the dependencies and to compile the project, the standard\n`rebar3` build tool is used:\n\n```sh\nrebar3 compile\n```\n\n### Flashing the device\n\nThe device port will vary depending on the chipset you use, but\nnormally will be bound to `/dev/ttyUSB0` or `/dev/ttyACM0`.\n\n```sh\nrebar3 atomvm esp32_flash -p $DEVICE_PORT\n```\n\n### Documentation\n\nDocumentation is provided via `ex_doc`, and can be generated with\nrebar3:\n\n```sh\nrebar3 ex_doc\n```\n\n## References\n\n  - [ESP32C3](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf)\n  - [AHT20](https://asairsensors.com/wp-content/uploads/2021/09/Data-Sheet-AHT20-Humidity-and-Temperature-Sensor-ASAIR-V1.0.03.pdf)\n  - [SSD1306](https://www.alldatasheet.com/datasheet-pdf/pdf/1179026/ETC2/SSD1306.html)\n  - [WS2812 LED](https://www.alldatasheet.com/datasheet-pdf/pdf/553088/ETC2/WS2812.html)\n  - [AtomVM](https://atomvm.net)\n  - [Ordinatra](https://ordinatra.com/)\n  - [ESL](http://erlang-solutions.com/)\n\n## Contributing\n\nWe welcome any contributions to the project, via hardware design\nenhancements or new software features. Whether you are submitting a\nfix or a new feature, your input is valuable. Here is a few guidelines\nfor making it easier to contribute:\n\n  - Report issues\n  - Submit patches\n  - Review hardware and software\n  - Update documentation\n  - Stay engaged\n\n## License\n\n```\nCopyright © 2024, Erlang Solutions Ltd.\n\nApache License, Version 2.0\n```\n\n## Acknowledgements\n\n  - [Omer Kilic](https://github.com/omerk) for making this awesome board\n  - [Ricardo Lanziano](https://github.com/arpunk) for writing the firmware application\n  - [AtomVM](https://atomvm.net) team for their hard work\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesl%2Fc3card","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesl%2Fc3card","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesl%2Fc3card/lists"}