PythonAgent.md

Python Agent

The Bang Python agent, arduino_exec.py, is the host-side genius that makes your Arduino a command-line overlord! Running on a PC, Mac, or Linux, it listens for ! (shell), & (sketch uploads), and @ (macro) commands over Serial-USB, turning your BANG("echo Hello") or BANG("@play") into pure magic. With a slick in-memory dictionary for dynamic @macro management, it’s the key to music playback, sketch swapping, and more, all while keeping your Arduino projects lean. Let’s unpack this powerhouse!

Overview

• Purpose: Processes Arduino commands, executing shell commands, uploading sketches, and managing user-defined macros.
• File: arduino_exec.py, a Python script using pyserial for Serial communication.
• Key Features:
  • Executes !command (e.g., !echo Hello runs echo Hello).
  • Uploads sketches with &sketch_name\n (e.g., &blink\n uses arduino-cli).
  • Manages @macro_name dynamically via an in-memory dictionary, supporting @add_macro, @delete_macro, @list_macros.

Setup

• Requirements: Python 3, pyserial (pip3 install pyserial), arduino-cli for uploads.

• Run Command:

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

  • -p: Serial port (e.g., COM3, /dev/cu.usbserial-00100).
  • -b: Baud rate (default 38400).
  • sudo: Needed for privileged commands (e.g., !reboot, @reboot).

• See Installation for setup details.

Command Processing

arduino_exec.py listens on the serial port for commands from the Arduino (sent via BANG macros or bang.serial()):

• Shell Commands (!):

  • Example: BANG("echo Hello World") sends !echo Hello World.

  • Script runs execute_command("echo Hello World"), outputting Hello World to Serial.

    if cmd_id == '!':
        result = execute_command(command)  # Runs shell command

• Sketch Uploads (&):

  • Example: BANG("&blink\n") sends &blink\n.

  • Script runs compile_and_upload("blink"), using arduino-cli to upload blink.ino.

    if cmd_id == '&':
        result = compile_and_upload(command)  # Uploads sketch

• Macros (@):

  • Stored in an in-memory macros dictionary (e.g., macros = {"play": "osascript -e 'tell application \"Music\" to play'"}).

  • Invoke: BANG("@play") runs execute_command(macros["play"]).

  • List: BANG("@list_macros") returns macro list (e.g., "play": "osascript ...").

  • Define: BANG("@add_macro:play:osascript -e 'tell application \"Music\" to play'") adds to macros.

  • Delete: BANG("@delete_macro:play") removes from macros.

    macros = {}  # In-memory dictionary
    if cmd_id == '@':
        if command in macros:
            result = execute_command(macros[command])
        elif command == "list_macros":
            macro_list = [f'    "{m}": "{macros[m]}"' for m in macros]
            result = "Registered Macros:\n" + "\n".join(macro_list)
        elif command.startswith("add_macro:"):
            _, macro_name, macro_cmd = command.split(":", 2)
            create_macro(macro_name, macro_cmd, macros)
            result = f"Macro '{macro_name}' created with command '{macro_cmd}'"
        elif command.startswith("delete_macro:"):
            _, macro_name = command.split(":", 1)
            result = delete_macro(macro_name, macros)
        else:
            result = f"unrecognized macro command: @{command}"

• Text Lines (#): Echoes text (e.g., BANG("#Hello") returns Hello).

• Output: Results are sent back to the Arduino’s Serial Monitor.

Configuring Macros

• In-Memory Storage: macros dictionary stores macro names and commands, reset on arduino_exec.py restart (no file-based storage like macros.json).

• Dynamic Management:

  • Add: BANG("@add_macro:weather:curl wttr.in?format=3").
  • Invoke: BANG("@weather").
  • Delete: BANG("@delete_macro:weather").
  • List: BANG("@list_macros").

• Predefining Macros: Add to arduino_exec.py:

  macros = {
      'play': 'osascript -e "tell application \"Music\" to play"',
      'pause': 'osascript -e "tell application \"Music\" to pause"'
  }

• Privileges: Use sudo for macros like @reboot (e.g., BANG("@add_macro:reboot:reboot")).

Customization

• Extend Macros: Add complex logic in create_macro() (e.g., validate commands).
• Logging: Enhance print() statements for debugging.
• Future Storage: Add file-based persistence (e.g., save macros to macros.json), not yet implemented.

Troubleshooting

• Macro Not Found: Check with BANG("@list_macros") or define with @add_macro.
• Upload Fails: Verify arduino-cli setup and sketch file location.
• No Output: Check serial port, baud rate (38400), and sudo.
• See Troubleshooting for fixes.

Next Steps

• Explore Examples for sketches using !, &, and @.
• Check Dynamic Uploading for &sketch_name\n details.
• See FAQ for macro questions.

---

Back to Home | Next: Examples