Examples.md

Examples

Ready to see Bang flex its muscles? The Bang library’s examples/ folder is packed with sketches that show off its command-line domination, from firing shell commands (!) to uploading new sketches (&) and managing slick macros (@) via Serial-USB. Whether it’s blinking LEDs, playing music, or reprogramming your Arduino with BANG("&blink\n"), these examples prove Bang’s power while staying lean for Arduino’s tight memory. Let’s dive into the action and get your microcontroller rocking!

Overview

• Purpose: Demonstrate Bang’s features using practical sketches in the examples/ folder.
• Sketches:
  • blink.ino: Sends a shell command and blinks an LED.
  • cmd.ino: Fires multiple shell commands.
  • music.ino: Controls music playback.
  • reboot.ino: Reboots the host.
  • upload.ino: Uploads a new sketch for self-reprogramming.
• Features Shown:
  • Shell commands: BANG("echo Hello") sends !echo Hello.
  • Sketch uploads: BANG("&blink\n") uploads blink.ino.
  • Macros: Dynamic management with BANG("@add_macro:play:osascript ..."), BANG("@play"), BANG("@delete_macro:play").

Prerequisites

• Bang is set up (see Installation).
• arduino_exec.py is running with sudo (e.g., sudo python3 arduino_exec.py -p /dev/cu.usbserial-00100 -b 38400).
• Serial Monitor is open (Arduino IDE, 38400 baud).
• arduino-cli is installed for & uploads.

Example Sketches

blink.ino

• Purpose: Sends a shell command and blinks an LED on pin 13.

• Key Code:

  #include <Bang.h>
  Bang bang(Serial);
  
  void setup() {
      Serial.begin(38400);
      while (!Serial) ;
      pinMode(13, OUTPUT);
  }
  
  void loop() {
      BANG("echo Blink Example"); // Sends !echo Blink Example
      digitalWrite(13, HIGH);
      delay(1000);
      digitalWrite(13, LOW);
      delay(1000);
  }

• Output: Serial Monitor shows Blink Example, LED blinks every second.

• Use Case: Basic ! command testing with visual feedback.

cmd.ino

• Purpose: Sends multiple shell commands to show versatility.

• Key Code:

  #include <Bang.h>
  Bang bang(Serial);
  
  void setup() {
      Serial.begin(38400);
      while (!Serial) ;
  }
  
  void loop() {
      BANG("echo cmd example"); // Sends !echo cmd example
      delay(1000);
      BANG("date"); // Sends !date
      delay(1000);
      BANG("curl https://example.com"); // Sends !curl https://example.com
      delay(5000);
  }

• Output: Serial Monitor shows command results (e.g., cmd example, current date, webpage content).

• Use Case: Testing multiple ! commands for host interaction.

music.ino

• Purpose: Controls music playback on macOS using osascript.

• Key Code:

  #include <Bang.h>
  Bang bang(Serial);
  
  void setup() {
      Serial.begin(38400);
      while (!Serial) ;
  }
  
  void loop() {
      BANG("@add_macro:play:osascript -e 'tell application \"Music\" to play'"); // Define @play
      delay(1000);
      BANG("@play"); // Play music
      delay(5000);
      BANG("@add_macro:pause:osascript -e 'tell application \"Music\" to pause'"); // Define @pause
      delay(1000);
      BANG("@pause"); // Pause music
      delay(5000);
  }

• Output: Music plays/pauses, Serial Monitor may show macro confirmations (e.g., Macro 'play' created).

• Use Case: Demonstrates dynamic @macro definition and invocation.

reboot.ino

• Purpose: Reboots the host (requires sudo).

• Key Code:

  #include <Bang.h>
  Bang bang(Serial);
  
  void setup() {
      Serial.begin(38400);
      while (!Serial) ;
  }
  
  void loop() {
      BANG("@add_macro:reboot:reboot"); // Define @reboot
      delay(1000);
      BANG("@reboot"); // Reboot host
      delay(10000);
  }

• Output: Host reboots, Serial Monitor may show Macro 'reboot' created.

• Use Case: Shows @macro for privileged commands.

upload.ino

• Purpose: Uploads a new sketch for self-reprogramming.

• Key Code:

  #include <Bang.h>
  Bang bang(Serial);
  
  void setup() {
      Serial.begin(38400);
      while (!Serial) ;
  }
  
  void loop() {
      BANG("&blink\n"); // Sends &blink\n, uploads blink.ino
      delay(10000);
  }

• Output: Arduino restarts with blink.ino, Serial Monitor shows new sketch output.

• Use Case: Demonstrates & for unlimited app size (each sketch ≤ 32K).

Running the Examples

1. Open a sketch in Arduino IDE (e.g., examples/blink/blink.ino).
2. Connect your Arduino via USB.
3. Set Tools > Board (e.g., Arduino Uno) and Tools > Port.
4. Upload the sketch.
5. Open Serial Monitor (38400 baud) to view output.
6. Ensure arduino_exec.py is running with sudo.

Tips

• Macros: Use @list_macros to check defined macros, @add_macro for new ones.
• Uploads: Test & with simple sketches first, verify arduino-cli setup.
• Debugging: Add Serial.println() to log results.
• Sudo: Required for @reboot or !reboot.

Troubleshooting

• No Output: Check Serial Monitor baud rate (38400), port, and arduino_exec.py.
• Macro Fails: Use BANG("@list_macros") to verify macro exists.
• Upload Errors: Ensure arduino-cli and sketch files are accessible.
• See Troubleshooting for fixes.

Next Steps

• Check Dynamic Uploading for &sketch_name\n details.
• Explore Python Agent for arduino_exec.py customization.
• See FAQ for macro questions.

---

Back to Home | Next: Dynamic Uploading