Usage.md

Usage

Ready to make your Arduino a command-line superhero with Bang? This guide shows you how to wield the Bang library to blast shell commands (!), upload new sketches (&), and manage slick user-defined macros (@) via Serial-USB to a PC, Mac, or Linux host. With macros like BANG("echo Hello"), BANG("@add_macro:play:osascript ..."), and BANG("&blink\n"), you’ll be controlling the host, playing music, or reprogramming your Arduino like a pro. Bang’s built to keep things lean for Arduino’s tight memory, so let’s dive in and start dominating!

Prerequisites

• Bang is set up on your Arduino and host (see Installation).
• arduino_exec.py is running on the host with sudo (e.g., sudo python3 arduino_exec.py -p /dev/cu.usbserial-00100 -b 38400).
• Serial Monitor is open in the Arduino IDE (baud rate: 38400) for viewing output.
• (Optional) arduino-cli is installed for dynamic sketch uploads.

Using Bang

Bang lets your Arduino send three types of commands to the host, using the Bang class and its handy macros (BANG, BANG_P, BANG_S):

• Shell Commands (!): Run host shell commands (e.g., BANG("echo Hello World") sends !echo Hello World).
• Sketch Uploads (&): Upload a new sketch, replacing the current one (e.g., BANG("&blink\n") uploads blink.ino).
• User-Defined Macros (@): Define, invoke, or delete macros dynamically (e.g., BANG("@add_macro:play:osascript ..."), BANG("@play")).

Here’s how to use Bang in your Arduino sketches and manage those @macro commands.

1. Include and Initialize Bang

Add the Bang library to your sketch and set up the Bang object:

```cpp
#include <Bang.h>
Bang bang(Serial); // Single Serial stream for commands and output
```

OR, for separate command/output streams (e.g., with an FTDI module):

```cpp
#include <SoftwareSerial.h>
SoftwareSerial command_serial(10, 11); // RX, TX pins
Bang bang(command_serial, Serial); // Commands via command_serial, output via Serial
```

• Initialize Serial in setup():

  void setup() {
      Serial.begin(38400);
      while (!Serial) ; // Wait for Serial to connect
      // If using command_serial, initialize it too
      // command_serial.begin(38400);
  }

2. Send Shell Commands (!)

Use the BANG macros to send shell commands prefixed with !:

• Basic Command:

  BANG("echo Hello World"); // Sends !echo Hello World

  • Serial Monitor shows: Hello World.

• Flash Memory (PROGMEM):

  BANG_P(PSTR("date")); // Sends !date from flash

  • Saves RAM for static commands.

• Dynamic String:

  String cmd = "curl https://example.com";
  BANG_S(cmd); // Sends !curl https://example.com

  • Useful for runtime-generated commands.

• Examples:

  • Get the host’s date: BANG("date").
  • Fetch a webpage: BANG("curl https://example.com").
  • Reboot (requires sudo): BANG("reboot").

3. Manage User-Defined Macros (@)

Use @ commands to define, invoke, or delete macros stored in an in-memory dictionary on the host:

• Define Macro:

  BANG("@add_macro:play:osascript -e 'tell application \"Music\" to play'"); // Defines @play

  • Adds play to macros dictionary with the command.

• Invoke Macro:

  BANG("@play"); // Runs osascript -e 'tell application "Music" to play'

• List Macros:

  BANG("@list_macros"); // Returns list (e.g., "play": "osascript ...")

  • Serial Monitor shows: Registered Macros: "play": "osascript ...", ....

• Delete Macro:

  BANG("@delete_macro:play"); // Removes @play

• Notes:

  • Macros persist in-memory during arduino_exec.py’s runtime, resetting on restart (no file-based storage like macros.json).
  • Use sudo for privileged macros (e.g., BANG("@add_macro:reboot:reboot")).
  • See Python Agent for advanced macro management.

4. Upload New Sketches (&)

Use &sketch_name\n to upload a new sketch, replacing the current one:

• Example:

  BANG("&blink\n"); // Sends &blink\n, uploads blink.ino

  • arduino_exec.py runs arduino-cli to compile/upload blink.ino, restarting the Arduino.

• Unlimited App Size:

  • Each sketch must fit in 32K flash, but you can swap subsystems endlessly.
  • If blink.ino includes Bang, it can send BANG("&cmd\n"), continuing the cycle.

• Setup:

  • Ensure arduino-cli is installed and configured (see Installation).
  • Place sketch files (e.g., blink.ino) where arduino_exec.py can access them.

• Example Flow:

  • Sketch sends BANG("&blink\n").
  • Host uploads blink.ino, which sends BANG("echo Blink Example").
  • Next sketch could send BANG("&music\n").

5. Example Sketch

Here’s a sketch combining all command types:

```cpp
#include <Bang.h>
Bang bang(Serial);

void setup() {
    Serial.begin(38400);
    while (!Serial) ;
}

void loop() {
    BANG("echo Hello World"); // Shell command
    delay(1000);
    BANG("@add_macro:play:osascript -e 'tell application \"Music\" to play'"); // Define macro
    delay(1000);
    BANG("@play"); // Play music
    delay(5000);
    BANG("@list_macros"); // List macros
    delay(1000);
    BANG("@delete_macro:play"); // Delete macro
    delay(1000);
    BANG("&blink\n"); // Upload new sketch
    delay(10000);
}
```

• Output (Serial Monitor):
  • Hello World from !echo Hello World.
  • Music plays from @play (if defined).
  • Macro list from @list_macros.
  • Arduino restarts with blink.ino after &blink\n.

6. Viewing Output

• Open the Serial Monitor (Arduino IDE, 38400 baud) to see command results:
  • Shell: Hello World from BANG("echo Hello World").
  • Macro: Confirmation or output (e.g., @play logs “Macro 'play' executed”).
  • Upload: Upload status or new sketch output.
• Ensure arduino_exec.py is running to process commands.

Tips

• Macro Management: Use @list_macros to check defined macros, @add_macro for new ones, and @delete_macro to clean up.
• Upload Safety: Test &sketch_name\n with simple sketches first, ensuring arduino-cli works.
• Sudo: Run arduino_exec.py with sudo for !reboot, @reboot, or similar.
• Debugging: Add Serial.println() to log command results.

Troubleshooting

• No Output: Check Serial Monitor baud rate (38400), port, and arduino_exec.py status.
• Macro Fails: Verify @macro_name is defined (use @list_macros or @add_macro).
• Upload Errors: Ensure arduino-cli is set up and sketch files are accessible.
• See Troubleshooting for more fixes.

Next Steps

• Explore Examples to see blink.ino, music.ino, and upload.ino in action.
• Dive into Python Agent for advanced @macro configuration.
• Check Dynamic Uploading to master &sketch_name\n.

---

Back to Home | Next: Code Structure