# Badge Magic: Bluetooth LED Badge App and Firmware > Badge Magic is FOSSASIA's documentation and source hub for controlling LED name badges over Bluetooth Low Energy. The documented mobile workflow is straightforward, but app installation, slot switching, licensing, and device compatibility require separate verification. **fossasia/badgemagic.fossasia.org** — Badge Magic Documentation https://badgemagic.fossasia.org - Repository: https://github.com/fossasia/badgemagic.fossasia.org - Stars: 1,514 · Forks: 5 - Language: Unknown - License: not declared - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/fossasia-badgemagic-fossasia-org ## Badge Magic's Scope Across Apps, Firmware, and Hardware Badge Magic solves a narrow hardware-control problem: putting text, clipart, and simple animation onto an LED name badge from a phone. The user does not need a general-purpose display programming environment for the basic workflow described in the documentation. They type a message, put the badge into Bluetooth transfer mode, and send the content from an app. The FOSSASIA project is better understood as a documentation site and project hub than as one installable application. The repository contains a README, images, privacy-related files, shop content, and a custom `CNAME` for the documentation site. It links to separate repositories for the Flutter app, Python tooling, Rust tooling, Go tooling, badge firmware, hardware, and the enclosure. That split matters because this page tells an adopter where the implementation lives, but it does not contain the app source or a buildable firmware tree itself. The documented audience includes Android and iPhone users who want ready-made app downloads, plus developers interested in the linked implementations. The README also mentions a Python option and provides a Python workshop. It does not specify supported badge models, minimum phone versions, badge dimensions, pixel layouts, or BLE chipset requirements, so hardware compatibility cannot be inferred from the page alone. ## BLE Message Transfer from Phone to LED Badge The transfer path uses Bluetooth Low Energy rather than conventional manual Bluetooth pairing. The README instructs the user to enable Bluetooth on the phone and connect automatically to the badge through BLE. That removes the operating system's normal pair-device step, but it also means the badge's BLE implementation and the app's protocol expectations must match. The physical sequence starts with the badge. One press of the top side button turns it on, while another press activates Bluetooth mode and reveals a Bluetooth icon on the display. The user then enters a message in the app and chooses the app's transfer or send action. According to the documentation, the badge updates and shows the new message after transmission. The second side button controls the displayed content and brightness. Short use is documented as a way to cycle through stored message slots. Holding the button changes LED brightness, either increasing or decreasing it. App support for slot switching is explicitly described as still being updated and planned for a future release, so users should not assume that message management is complete in the current apps. The repository does not document packet formats, service and characteristic UUIDs, message limits, refresh behavior, error handling, reconnection rules, or transfer latency. Those protocol details would need to be checked in the app and firmware repositories before modifying either side. ## Choosing an App for Android, iOS, or Python For a first mobile use, the documentation directs Android users to Google Play and F-Droid. It separately links an App Store listing for iOS. The listed Android package identifier is `org.fossasia.badgemagic`, while the Apple listing is published as Badge Magic App. These links support installation through normal mobile distribution channels rather than source builds. The README does not give command-line installation steps, build prerequisites, release versions, or a checked-out source procedure. Consequently, there is no verified `flutter run`, `pip install`, Cargo, or Go command to reproduce from this repository. Installing a listed mobile app means obtaining it from the referenced store, while building from source requires moving to the linked implementation repository and following the documentation there. The project hub identifies the main Badge Magic app as Flutter-based and says that its code targets Android, iOS, Linux, macOS, and Windows. It also links a Python app repository and a Rust app repository. A Go app repository is listed as well. The page describes the Python option as available in the transfer instructions but gives no installation command, so the linked Python workshop is the documented next source of setup detail. For a new user, the first real test should remain the README's basic path: install the appropriate mobile app, enable phone Bluetooth, enter short text, put the badge into transfer mode, and send it. A short message reduces uncertainty while confirming whether the phone, app, badge, and BLE protocol belong together. ## Separate Source Trees Shape Modification and Upgrade Work Maintenance work is distributed across several repositories. The Flutter repository contains the principal mobile and desktop application. The linked `led-name-badge-ls32` repository contains the Python app, `badgemagic-rs` contains the Rust app, and `badgemagic-go` contains the Go app. Firmware is maintained separately in `badgemagic-firmware`, while physical design files are divided between `badgemagic-hardware` and `badgemagic-case`. This separation lowers the amount of code an adopter must inspect for a narrow change. Someone editing only the phone interface can focus on the Flutter repository, while firmware debugging belongs in the firmware tree. It also raises coordination cost. A change to the BLE message format may need matching updates on both sides, but the README does not document a compatibility matrix or release process tying the app versions to firmware versions. The documentation repository is not archived, and its last push was on 2026-07-04. It has no GitHub releases, so there is no release tag or packaged documentation version to compare. A recent documentation push does not by itself establish that every linked app or firmware repository receives equally recent updates. Those repositories have their own histories and requirements. The README identifies `badgewitch` as community-developed third-party firmware with an enhanced menu and `rustbadge` as a Rust demo with two-level shading support. It states that their authors are not affiliated with FOSSASIA. They are alternatives to investigate only when their target hardware and functions match the badge in hand. ## Licensing and Documentation Gaps Block Distribution Decisions The repository metadata for Badge Magic does not identify a license, and the README does not state one. The documentation site therefore establishes where to find the code and how the basic transfer workflow is supposed to work, but it does not establish reuse or redistribution rights for this repository or the linked projects. Each source repository and third-party firmware project needs its own license inspection. That absence is particularly relevant because this ecosystem spans application code, firmware, hardware designs, and a case design. Permission to modify the Flutter interface does not imply permission to distribute a badge image, and permission for firmware does not settle questions about hardware files. No legal conclusion should be drawn from the presence of source links or from FOSSASIA authorship. The documentation also leaves several operational questions unanswered. It does not state how to update a badge's firmware, how to roll back an app or firmware version, or what to do when a transfer fails halfway through. It also does not explain whether brightness settings persist, whether multiple message slots are stored in flash memory, or how the app behaves when more than one nearby badge advertises itself. These are concrete gaps for an adopter, not merely missing promotional detail. ## Where Badge Magic Differs from Generic BLE Tools Its apps prepare display content and provide transfer actions aimed at a badge that is already in the correct physical mode. The badge's button sequence, Bluetooth icon, message slots, and brightness controls are part of that interaction. The linked community firmware projects differ in scope. `badgewitch` is presented as firmware with an enhanced menu, while `rustbadge` is presented as a Rust demonstration of two-level shading. These are not described as interchangeable command-line replacements for the mobile apps, and the README gives no installation or flashing procedure for either project. Their practical difference is firmware behavior and implementation, but compatibility cannot be determined without checking each project's target hardware documentation. Badge Magic is therefore the wrong choice for someone who needs an iOS or Android SDK that can drive an arbitrary display. It is also insufficient as the sole source for firmware installation or low-level BLE protocol development. It fits users who want the named badge experience and developers willing to inspect the separate source repositories for implementation detail. ## Conclusion Badge Magic is a reasonable starting point for someone who owns a compatible LED badge and wants open-source app or firmware options. It is not a complete installation guide, and the repository does not confirm badge models, BLE protocol compatibility, or licensing. Before adopting it, verify that your badge uses the expected BLE transfer method, choose the relevant source repository, and inspect its license before distributing modifications. ## FAQ ### How do I transfer a message to a Badge Magic LED badge? Enable Bluetooth on the phone, enter text in the app, press the badge's top button once to turn it on and again to activate Bluetooth mode, then choose Transfer or Send. The README says the badge will update and display the new message. ### Do I need to pair my phone with the Badge Magic badge? No manual pairing is required according to the README. The apps use Bluetooth Low Energy for the connection, although the documentation does not list the BLE profiles or device models that must be compatible. ### Can I switch between stored messages on the Badge Magic badge? The badge's second button is documented as the control for cycling through stored message slots. Full app support for this feature is described as still being updated and planned for an upcoming release. ### Where can I get the Badge Magic app? Android users are directed to Google Play and F-Droid, and iOS users are directed to the App Store. The README also links separate source repositories for Flutter, Python, Rust, Go, and firmware development. ## Sources - [fossasia/badgemagic.fossasia.org on GitHub](https://github.com/fossasia/badgemagic.fossasia.org) - [Issues](https://github.com/fossasia/badgemagic.fossasia.org/issues) - [README](https://github.com/fossasia/badgemagic.fossasia.org/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fossasia-badgemagic-fossasia-org