Welcome to the Bang wiki!
# Bang Wiki

Welcome to the Bang Wiki for [Bang](https://github.com/ripred/Bang), the ultimate Arduino library that turns your microcontroller into a command-line king! Bang lets your Arduino blast shell commands, custom macros, and even new sketches to a PC, Mac, or Linux host via Serial-USB, grabbing results like a champ. With macros like `BANG("@play")` for custom shortcuts, `BANG("echo Hello")` for shell commands, and `BANG("&blink\n")` to reprogram itself, Bang obliterates the 32K flash limit, letting your application scale to epic proportions—each uploaded sketch just needs to fit in 32K. Include Bang in the new sketch, and it keeps dishing out commands, making your Arduino a self-rewriting legend. This wiki’s your roadmap to dominating with Bang, from macros to self-reprogramming, for Arduino hackers, IoT gurus, and boundary-breakers.

## What Bang Does
Bang puts your Arduino in charge with these badass features:
- **Shell Commands with Macros**: Fire `BANG("echo Hello")` to send `!echo Hello` to the host’s shell, getting results back. Use `BANG_P(PSTR("date"))` for flash memory or `BANG_S(String("curl https://example.com"))` for dynamic strings.
- **Custom Macros**: Drop `BANG("@play")` to trigger a user-defined macro (e.g., play music), configured in `arduino_exec.py` for quick, reusable commands.
- **Self-Reprogramming**: Slam `BANG("&blink\n")` to upload a new sketch (e.g., `blink.ino`), swapping the current one. With Bang in the new sketch, it can send more `&`, `!`, or `@` commands, letting your app grow without limits—each subsystem fits in 32K flash.
- **Host Control**: Play tracks with `BANG("@play")` or `BANG("osascript -e 'tell application \"Music\" to play'")`, reboot with `BANG("reboot")` (needs `sudo`), or check host sleep status.
- **Host Power**: Access disk storage, fetch weather, control Hue lights, or run any script with `BANG("!...")` or `BANG("@macro")`.
- **Lean and Mean**: Runs in minimal RAM, built for Arduino’s tight constraints.

## Why Bang Rocks
Bang’s a total game-changer! It hands your Arduino the host’s full power—internet, storage, dynamic code swaps—all wrapped in slick macros like `BANG` and `@macro`. Build a smart IoT gadget, a music player, or a self-evolving sketch—the possibilities are endless! 😃

## Table of Contents
- [About](About.md): Dive into Bang’s goals and tech details.
- [Installation](Installation.md): Get Bang running on Arduino and host.
- [Usage](Usage.md): Master `BANG`, `@macro`, `!`, and `&` commands.
- [Code Structure](CodeStructure.md): Explore the library and Python agent.
- [Bang Class](BangClass.md): Learn the `Bang` class and macro magic.
- [Python Agent](PythonAgent.md): Understand `arduino_exec.py`’s `!`, `&`, `@` handling.
- [Examples](Examples.md): Check out sketches like `upload.ino`.
- [Dynamic Uploading](DynamicUploading.md): Unleash `&sketch_name\n` power.
- [Security](Security.md): Stay safe with `sudo` and sanitization.
- [Troubleshooting](Troubleshooting.md): Fix serial, upload, or macro issues.
- [Options](Options.md): Tweak baud rates, ports, and streams.
- [Performance](Performance.md): Boost serial and upload speed.
- [Testing](Testing.md): Validate commands, uploads, and macros.
- [Contributing](Contributing.md): Join the Bang crew.
- [License](License.md): MIT License details.
- [FAQ](FAQ.md): Quick answers to your questions.
- [Changelog](Changelog.md): Track Bang’s updates.

## Getting Started
1. Hit the [Installation](Installation.md) guide to set up Bang.
2. Jump to [Usage](Usage.md) to fire off `BANG("echo Hello")`, `BANG("@play")`, or `BANG("&blink\n")`.
3. Explore [Dynamic Uploading](DynamicUploading.md) to break the 32K barrier.

## Visuals
Bang’s output shines in the Serial Monitor, showing command results, macro triggers, or upload status. No visuals are in the repo yet, but imagine:
- Serial Monitor printing `Hello World` from `BANG("echo Hello World")`.
- Triggering `@play` to start music.
- Confirmation of `BANG("&blink\n")` uploading `blink.ino`.
See [Examples](Examples.md) and [Usage](Usage.md) for screenshot placeholders.

For bugs or contributions, check the [GitHub repository](https://github.com/ripred/Bang) or [Contributing](Contributing.md). Let’s make your Arduino rewrite the rules!

---
[Back to Top](#bang-wiki) | [Next: About](About.md)