# Badge Magic [](https://gitter.im/fossasia/badge-magic?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)  **Python Library to program via desktop https://github.com/fossasia/led-name-badge-ls32** **Magically Create Text and Draw Cliparts on LED Name Badges using Bluetooth** The Badge Magic app is a comprehensive LED badge management system that lets you create, customize, save, and transfer dynamic text and graphics to LED name badges via Bluetooth. The app features an intuitive interface with multiple creation modes, extensive animation options, and powerful customization tools. ## Key Features ### 🎨 **Multi-Mode Creation** - **Text Mode**: Create animated text with 22 different transition effects - **Draw Mode**: Freehand drawing with shape tools (square, rectangle, circle, triangle) - **Clipart Mode**: Import and use pre-made graphics - **Animation Mode**: Advanced animations including Pacman, hearts, fireworks, and more ### 🎭 **Animation & Effects** - **22 Animation Types**: Left, Right, Up, Down, Fixed, Splitting, Snowflake, Picture, Laser, Pacman, Chevron, Diamond, Broken Hearts, Cupid, Feet, Fish, Diagonal, Emergency, Beating Hearts, Fireworks, Digital Rain (Equalizer), and Cycle - **3 Visual Effects**: Flash, Invert, and Marquee - **Speed Control**: 8-speed radial dial for precise animation timing - **Transition Tab**: Quick access to basic animations ### 💾 **Badge Management** - **Save & Edit**: Save badges with original text preservation for easy editing - **Custom Slot Decider**: Select up to 8 badges for batch operations - **Import/Export**: Share badges between devices - **Badge Library**: Organized collection of saved creations ### 🎯 **Drawing Tools** - **Shape Tools**: Freehand, Square, Rectangle, Circle, Triangle - **Undo/Redo**: Full drawing history support - **Grid-Based**: Precise 11×44 LED grid editing - **Real-time Preview**: See changes as you draw - **Import from image**: It is possible to pixelate an image from the gallery ### 📱 **User Interface** - **4 Main Tabs**: Speed, Transition, Effects, and Animation - **Multi-language Support**: English and Hindi - **Settings Screen**: Bluetooth device management and scan preferences - **Navigation Drawer**: Easy access to all features ### 🔧 **Advanced Features** - **Bluetooth Alias Management**: Rename and manage connected devices - **Scan Settings**: Configure device discovery preferences - **USB transfer**: Transfer data to the badge trough USB - **Cross-Platform Support**: Works on Android, iOS, and Linux (mobile and desktop platforms) ### 👾 **FOSSASIA's firmware feature** The app lets you install our firmware! Go to the [badgemagic-firmware](https://github.com/fossasia/badgemagic-firmware) repository and follow the instructions to prepare the badge! - **USB firmware update**: Put your badge in ISP mode, choose your badge version, and you are done - **BLE firmware update**: This feature is in beta and is slower, but it lets you update the badge while the app is in the background - **Security PIN**: You can activate a security PIN to authorize the data transfers - **Badge Renaming**: You can rename your badge, to make it unique and recognizable by the app - **Streaming mode**: You can stream in real time what you are writing in the app on the badge The project is based on the work of [Nilhcem](https://github.com/Nilhcem) and has been significantly expanded with modern features and improved user experience. ## How It Works ### Creating Badges 1. **Text Creation**: Enter your message in the text field and choose from 22 different animations 2. **Speed Control**: Use the radial dial to set animation speed (8 levels from slow to very fast) 3. **Effects**: Apply visual effects like flash, invert, or marquee 4. **Preview**: See your badge in real-time on the virtual LED display 5. **Save**: Store your creation with a custom name for future use ### Drawing Badges 1. **Shape Tools**: Choose from freehand, square, rectangle, circle, or triangle 2. **Grid Editing**: Draw pixel-perfect on the 11×44 LED grid 3. **Undo/Redo**: Full drawing history support 4. **Save as Clipart**: Store your drawings for reuse ### Badge Management 1. **Saved Badges**: Access your library of created badges 2. **Custom Slot Selection**: Select up to 8 badges for batch operations 3. **Edit Mode**: Modify existing badges while preserving original text 4. **Import/Export**: Share badges between devices ### Bluetooth Transfer 1. **Device Discovery**: Automatic scanning for compatible LED badges 2. **Connection**: Secure Bluetooth Low Energy connection 3. **Transfer**: Send your badge data to the physical device 4. **Settings**: Configure scan preferences and device aliases ## Get Stable Versions ## Get Beta Versions (Built from the latest code) ## Download * [Latest Release Build](https://github.com/fossasia/badgemagic-app/raw/apk/badge-magic-development-release.apk) in the apk branch ## Permissions * **Bluetooth**: For connecting to and sending data to LED badges * **Storage**: For saving and loading badge designs and clipart * **Location** (Android 11 and below): Required by Android for Bluetooth Low Energy device discovery. For more information, see the [Android documentation](https://source.android.com/devices/bluetooth/ble) ## Privacy * See our [Privacy Policy](https://badgemagic.fossasia.org/privacy/) for details on data handling. ## Supported Platforms * **Android**: Full feature support with native Bluetooth integration * **iOS**: Complete functionality with TestFlight beta testing * **Linux**: Desktop support for development and testing ## Communication Please talk to us on the badge-magic [Gitter channel here](https://gitter.im/fossasia/badge-magic). ## Available Devices There are a number of devices with Bluetooth on the market. As far as we can tell they are mostly from the same manufacturer. When you get a device ensure it comes with Bluetooth. There are devices that don't support Bluetooth. These are not supported in the app currently. * Get one from the [FOSSASIA Shop here](https://fossasia.com/product/led-badge/) ## Screenshots ### App Interface Overview The app features a modern, tabbed interface with four main sections: 1. **Speed Tab**: Radial dial for controlling animation speed (8 levels) 2. **Transition Tab**: Quick access to basic text animations (Left, Right, Up, Down, Fixed) 3. **Effects Tab**: Visual effects (Flash, Invert, Marquee) 4. **Animation Tab**: Advanced animations including Pacman, Hearts, Fireworks, and more ### Key Screens - **Home Screen**: Main creation interface with text input and animation controls - **Draw Badge Screen**: Pixel-perfect drawing with shape tools and undo/redo - **Saved Badges Screen**: Badge library with custom slot selection for batch operations - **Settings Screen**: Bluetooth device management and language preferences ## Reverse-Engineering Bluetooth LE Devices Security in Bluetooth LE devices is optional, and many cheap products you can find on the market are not secured at all. This applies to our Bluetooth LED Badge. While this could lead to some privacy issues, this can also be a source of fun, especially when you want to use an LED Badge in a different way. It also makes it easy for us to get started with the development of a Free and Open Source Android app. As we understand how the Bluetooth LED badge works, converting a text to multiple byte arrays, we can send using the Bluetooth LE APIs. An indepth blog post about reverse-engineering the Bluetooth community [is here](http://nilhcem.com/iot/reverse-engineering-bluetooth-led-name-badge). The implementation in the Android app consists of manipulating bits. That may be tricky. A single bit error and nothing will work, plus it will be hard to debug. For those reasons, and since the specs are perfectly clear the reverse engineer Gautier Mechling strongly recommends to start writing unit tests before the code implementation. ## Branch Policy We have the following branches * **development**: All development goes on in this branch. If you're making a contribution, you are supposed to make a pull request to _development_. PRs to development branch must pass a build check on CI/CD. * **apk**: This branch contains many apk files, that are automatically generated on the merged pull request a) debug apk b) release apk - There are multiple files in the apk branch of the project, this branch consists of all the APK files and other files that are relevant when an APK is generated. - Once a pull request is merged, the previous APK branch is deleted and a new APK branch is created. - If a PR is merged in development branch then the new APKs for the development branch are generated whereas the APKs corresponding to the master branch are not regenerated and simply the previously generated files are added. * **version**: This branch stores the version information for the APKs (versionName and versionCode). This is used in our workflows for automatic versioning wherein the next version information is automatically fetched from this branch and used for building APKs. * **fastlane***: These branches contain information and metadata used by fastlane to automate deployment. * **pr-screenshots**: This branch stores screenshots for every open pull request, which are shown in comments in every pull request. ## Contributions Best Practices Please read FOSSASIA's [Best Practices](https://blog.fossasia.org/open-source-developer-guide-and-best-practices-at-fossasia/) before contributing. Please help us follow the best practice to make it easy for the reviewer as well as the contributor. We want to focus on the code quality more than on managing pull request ethics. Here are some basics: * Single commit per pull request * For writing commit messages please read the [CommitStyle.md](docs/commitStyle.md). * Follow uniform design practices. The design language must be consistent throughout the app. * The pull request will not get merged until and unless the commits are squashed. In case there are multiple commits on the PR, the commit author needs to squash them and not the maintainers cherrypicking and merging squashes. * If the PR is related to any front end change, please attach relevant screenshots in the pull request description. * Before you join development, please set up the project on your local machine, run it and go through the application completely. Press on any button you can find and see where it leads to. Explore. * If you would like to work on an issue, drop in a comment at the issue. If it is already assigned to someone, but there is no sign of any work being done, please free to drop in a comment and start working on it. ## Release Process ### Beta Release Flow * All merged pull requests into the development branch are automatically included in the beta version of the app. * The beta builds are automatically pushed to: - Google Play Store (Beta Track) - Apple TestFlight (iOS Beta) This allows contributors and testers to try out the latest features and verify stability before the app is released to all users. ### Production Release Flow * A new GitHub release (using the "Releases" tab) is the trigger for publishing a production version. * When a GitHub release is created: - The latest beta APK or iOS build is promoted to the production track on the respective app stores. - No additional code changes are made unless specified. This ensures that the version tested in beta is the exact one released to the public. ### Notes * Please ensure all features and fixes are tested and merged into development before a GitHub release is created. * Versioning and changelogs should be updated accordingly. * If any hotfixes are required post-release, they should go through the same flow (PR → beta → release). ## Local Development Setup Follow these steps to set up and run Badge Magic on your local machine without a Dev Container. ### Prerequisites Before starting, install the following tools: * **[Git](https://git-scm.com/downloads)**: Required for version control. * **[Flutter SDK](https://docs.flutter.dev/get-started/install)**: The repository requires Flutter `3.47.5` (or compatible stable release) as defined in [`pubspec.yaml`](pubspec.yaml). Flutter comes bundled with a compatible **Dart SDK** (Dart `>=3.3.4 <4.0.0`). * **Platform Tooling** (depending on your target platform): * **Android**: [Android Studio](https://developer.android.com/studio) or Android SDK Command-line Tools with Android SDK Platform, Build-Tools, and JDK 17 or 21. * **iOS** (macOS only): [Xcode](https://developer.apple.com/xcode/) and CocoaPods. * **Linux**: Native build essentials (`clang`, `cmake`, `ninja-build`, `pkg-config`, `libgtk-3-dev`). Run `flutter doctor` in your terminal to verify that Flutter and required toolchains are properly configured. ### Clone the Repository Clone the repository and enter the project directory: ```bash git clone https://github.com/fossasia/badgemagic-app.git cd badgemagic-app ``` Per our [Branch Policy](#branch-policy), all development takes place on the `development` branch. Check out `development` and create a dedicated feature or bugfix branch: ```bash git checkout development git pull origin development git checkout -b ``` ### Install Dependencies Fetch all project dependencies specified in `pubspec.yaml`: ```bash flutter pub get ``` ### Run the Application 1. Check available connected physical devices, emulators, or desktop targets: ```bash flutter devices ``` 2. Start the application: ```bash flutter run ``` If multiple targets are available, specify your chosen target using its device ID: ```bash flutter run -d ``` Note that mobile targets (Android and iOS) and Linux desktop are the primary supported development environments (see [Supported Platforms](#supported-platforms)). Different platforms may require platform-specific configuration before running. ### Device and Platform Configuration * **Android Device Debugging**: Enable **Developer options** and **USB debugging** on your physical Android device (or launch an Android Virtual Device via Android Studio). Connect via USB and confirm the device is detected and authorized with `adb devices`. * **iOS Development** (macOS only): Ensure Xcode command-line tools are installed. If CocoaPods dependencies need updating, run `pod install` in the `iOS` directory. * **Linux Desktop**: Ensure required GTK and system build dependencies are installed before building. * **Bluetooth & Hardware Testing**: Testing Bluetooth Low Energy (BLE) scanning and badge data transmission requires a physical device with Bluetooth turned on. Grant Bluetooth permissions (and Location permissions on Android 11 and below) when prompted by the app. Virtual emulators and simulators typically do not support Bluetooth Low Energy hardware. * **Dev Container**: If you prefer an automated containerized environment with Android debugging support, see the [Dev Container usage](#dev-container-usage) section below. ### Basic Troubleshooting * **`flutter` command not found**: Ensure the Flutter SDK's `bin` directory is added to your system's `PATH` environment variable. * **Missing toolchains or licenses**: Run `flutter doctor` to identify missing components. If Android licenses are unaccepted, run: ```bash flutter doctor --android-licenses ``` * **No connected device detected**: Run `flutter devices` to check recognized targets. For Android, ensure `adb devices` lists your device and that USB debugging is authorized on your phone screen. * **Dependency resolution errors**: Run `flutter pub get`. If issues persist, clean cached artifacts and re-fetch dependencies: ```bash flutter clean flutter pub get ``` ## Dev Container usage Opening this repository in VSCode, GitHub Codespaces or another supported editor/IDE will allow the repository to be opened in a [Dev Container](https://containers.dev/). The Dev Container contains all necessary dependencies and tools required to build, run and debug flutter applications. ### How to connect via `adb` :warning: In case `adb` is already installed and running on the host it may need to be stopped before continuing. This Dev Container allows several different methods of connecting to a device via `adb`: #### Entirely from inside the container (USB pass-through) :information_source: **Windows** and **MacOS** need a working **USB/IP** setup. Read more in the official [Docker Desktop documentation](https://docs.docker.com/desktop/features/usbip/) and in this [blog post](https://blog.golioth.io/usb-docker-windows-macos/). The Dev Container bind-mounts `/dev/bus/usb/` and sets the correct access controls for a seamless integration. \ Enable [USB debugging](https://developer.android.com/tools/adb#Enabling) on your phone and try to find it via: ```bash adb devices ``` If it shows up, everything is ready and you can run `flutter run` to push a development version of the app onto your device. #### Using the host's `adb` server If `adb` is already installed on the host, the tools in the Dev Container can be configured to use the host's `adb` server: 1. Ensure the `adb` server is listening on **all interfaces** 1. If that is not the case, kill and restart it: `adb kill-server && adb -a server` (the `-a` instructs it to listen on all interfaces). 1. Set or export the following environment variable before executing `adb` or `flutter run`: `ADB_SERVER_SOCKET=tcp:host.docker.internal:5037` 1. You should now be able to list the devices connected via USB to the host #### Wireless connection Android 11 and higher support wireless debugging. Check out the [documentation](https://developer.android.com/tools/adb#wireless-android11-command-line) for more information. \ For this mode it is required that both the workstation and the device are on the **same network**. :information_source: This also works when developing inside **GitHub Codespaces**. In that case you can bring your device and the Codespace onto the same network by installing WireGuard, Tailscale or another overlay/mesh network on both the Codespace and your device. Enable Wireless debugging as per the [documentation](https://developer.android.com/tools/adb#wireless-android11-command-line), then **pair** `adb pair :` and **connect** `adb connect :` and you should be able to find your device via `adb devices`. ## LICENSE The application is licensed under the [Apache License 2.0](/LICENSE). Copyright is owned by FOSSASIA and its contributors. ## OTHER BADGE APPS * [LED Python App](https://github.com/fossasia/led-name-badge-ls32)