Installation.md

Installation

Ready to unleash the power of Bang and turn your Arduino into a host-dominating beast? This guide walks you through setting up the Bang library, getting your Arduino and host (PC, Mac, or Linux) ready to fire off shell commands (!), custom macros (@), and self-reprogramming sketches (&). You’ll be sending BANG("echo Hello") or BANG("&blink\n") in no time, all while keeping it lean for Arduino’s tight memory limits. Let’s dive in and make your microcontroller a command-line legend!

Prerequisites

Before you start, gather these essentials:

• Arduino Board: Any Arduino with Serial-USB (e.g., Uno, Nano). No extra hardware needed, but an FTDI module is optional for dual streams.
• Host Machine: PC, Mac, or Linux with a USB port and Python 3 installed.
• USB Cable: To connect the Arduino to the host.
• Software:
  • Arduino IDE (or arduino-cli for dynamic uploads).
  • Python 3 and pyserial for the host agent.
  • Git (optional, for cloning the repo).
• Admin Privileges: For commands or macros requiring sudo (e.g., BANG("reboot"), BANG("@reboot")).

Step-by-Step Setup

1. Clone or Download the Repository

   • Option 1: Clone with Git:

     git clone https://github.com/ripred/Bang.git

   • Option 2: Download ZIP:
     • Grab the ZIP from GitHub and extract it to a folder.
   • The repo includes Bang.h, Bang.cpp, arduino_exec.py, and examples/ (e.g., upload.ino, music.ino).

2. Install the Arduino IDE

   • Download from https://www.arduino.cc/en/software and install for your OS (Windows, macOS, Linux).
   • Skip if you’re using arduino-cli for uploads (see step 6).

3. Add the Bang Library to Arduino

   • Copy the Bang folder (containing Bang.h and Bang.cpp) to your Arduino libraries folder:
     • Windows: Documents/Arduino/libraries/
     • macOS/Linux: ~/Documents/Arduino/libraries/
   • Alternatively, in the Arduino IDE:
     • Go to Sketch > Include Library > Add .ZIP Library, select the Bang folder or ZIP.
   • Verify the library is recognized: Sketch > Include Library should list “Bang”.

4. Install Python and pyserial on the Host

   • Ensure Python 3 is installed (check with python3 --version).
   • Install pyserial:

     pip3 install pyserial

   • This powers arduino_exec.py to handle Serial communication.

5. Set Up arduino-cli for Dynamic Uploads (Optional)

   • For BANG("&blink\n") to work, install arduino-cli:
     • Download from https://arduino.github.io/arduino-cli.
     • Follow setup instructions for your OS (e.g., brew install arduino-cli on macOS).
   • Configure arduino-cli:

     arduino-cli config init
     arduino-cli core update-index
     arduino-cli core install arduino:avr

   • Needed for arduino_exec.py to compile/upload sketches (e.g., blink.ino).

6. Prepare the Python Agent

   • Copy arduino_exec.py from the repo to a folder on your host (e.g., ~/Bang/).
   • Identify your Arduino’s serial port:
     • Windows: Check Device Manager (e.g., COM3).
     • macOS/Linux: Run ls /dev/cu.* or ls /dev/tty.* (e.g., /dev/cu.usbserial-00100).
   • Run arduino_exec.py with sudo for privileged commands (e.g., !reboot, @reboot):

     sudo python3 arduino_exec.py -p /dev/cu.usbserial-00100 -b 38400

     • -p: Serial port (replace with your port).
     • -b: Baud rate (default 38400, adjustable).
   • Keep arduino_exec.py running to process !, &, and @ commands.

7. Configure User-Defined Macros (Optional)

   • To use @macro_name (e.g., BANG("@play")), edit arduino_exec.py to map macros to actions:
     • Open arduino_exec.py in a text editor.
     • Add logic to handle @ commands, e.g.:

       if line.startswith('@play'):
           subprocess.run(['osascript', '-e', 'tell application "Music" to play'])
       elif line.startswith('@reboot'):
           subprocess.run(['reboot'])

     • Save and restart arduino_exec.py with sudo for privileged macros.
   • See Python Agent for detailed macro setup.

8. Upload an Example Sketch

   • Open the Arduino IDE and load an example from the examples/ folder (e.g., examples/blink/blink.ino).
   • Connect your Arduino via USB.
   • In the IDE:
     • Select your board: Tools > Board (e.g., Arduino Uno).
     • Select the port: Tools > Port (e.g., /dev/cu.usbserial-00100).
   • Click Upload to flash the sketch.
   • Open the Serial Monitor (Tools > Serial Monitor, baud rate 38400) to see output (e.g., Hello World from BANG("echo Hello World")).

9. Test the Setup

   • With arduino_exec.py running and a sketch like blink.ino uploaded:
     • Check the Serial Monitor for output (e.g., Blink Example from BANG("echo Blink Example")).
     • Try upload.ino to test BANG("&blink\n"), which should upload blink.ino.
     • Test a macro if configured (e.g., BANG("@play") to start music).
   • See Usage for command examples.

Troubleshooting

• Serial Monitor Blank: Ensure baud rate is 38400, the correct port is selected, and arduino_exec.py is running.
• Upload Fails: Verify arduino-cli is installed and configured, and the sketch file (e.g., blink.ino) is accessible to arduino_exec.py.
• Macro Not Working: Check @macro_name definitions in arduino_exec.py (see Python Agent).
• Permission Errors: Run arduino_exec.py with sudo for !reboot or @reboot.
• See Troubleshooting for more fixes.

Next Steps

• Jump to Usage to start firing BANG("echo Hello"), BANG("@play"), or BANG("&blink\n").
• Explore Python Agent for advanced @macro setup.
• Check Dynamic Uploading to master self-reprogramming.

---

Back to Home | Next: Usage