openswarm-slave 0.1.0__py3-none-any.whl

openswarm_slave/__init__.py

@@ -0,0 +1,12 @@
+"""
+OpenSwarm Linux Slave SDK (`openswarm-slave`)
+=============================================
+Turns any Linux system (Arduino UNO Q, Portenta X8, Raspberry Pi, Nvidia Jetson, or Linux Laptop)
+into a Zero-Control-Logic OpenSwarm Slave node speaking the exact same UDP protocol (4210 / 4211)
+as the microcontroller slaves.
+"""
+
+from .node import SwarmNode
+
+__version__ = "0.1.0"
+__all__ = ["SwarmNode"]

openswarm_slave/cli.py

@@ -0,0 +1,27 @@
+"""
+OpenSwarm Linux Slave CLI (`openswarm-slave`)
+Turns any Linux SBC (Arduino UNO Q, Portenta X8, Raspberry Pi, Jetson) or laptop
+into an active OpenSwarm Slave node right from the terminal.
+"""
+
+import argparse
+from .node import SwarmNode
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="OpenSwarm Linux Slave Agent")
+    parser.add_argument("--id", default="linux_node", help="Slave Node ID (default: linux_node)")
+    parser.add_argument("--port", type=int, default=4210, help="UDP Port (default: 4210)")
+    parser.add_argument("--led-pin", type=int, default=2, help="Register a GPIO pin as 'led' (default: 2)")
+    args = parser.parse_args()
+
+    node = SwarmNode(args.id, udp_port=args.port)
+    node.register_digital_output("led", args.led_pin)
+    node.register_cpu_temp("cpu_temp")
+    node.register_system_load("sys_load")
+    node.register_wifi_rssi("rssi")
+    node.start(block=True)
+
+
+if __name__ == "__main__":
+    main()

openswarm_slave/hal_linux.py

@@ -0,0 +1,381 @@
+"""
+Linux Hardware Abstraction Layer (`LinuxHAL`)
+Supports:
+- Arduino UNO Q (Linux + MCU bridge / sysfs / libgpiod)
+- Arduino Portenta X8 (NXP i.MX 8M Mini Linux sysfs / libgpiod / I2C / SPI / UART)
+- Raspberry Pi (RPi.GPIO / libgpiod / sysfs / I2C / SPI / UART)
+- Nvidia Jetson (Jetson.GPIO / sysfs / I2C / SPI / UART)
+- Generic Linux Laptop / Desktop (sysfs thermal/network + virtual GPIO simulation for testing)
+"""
+
+import os
+import platform
+import socket
+import struct
+import time
+from typing import Any, Dict, List, Optional, Tuple
+
+
+class LinuxHAL:
+    def __init__(self, verbose_sim: bool = True):
+        self.verbose_sim = verbose_sim
+        self.board_name = self._detect_board()
+        self._gpio_backend = "sim"
+        self._rpi_gpio = None
+        self._pwm_instances: Dict[int, Any] = {}
+        self._sim_pins: Dict[int, int] = {}
+        self._i2c_buses: Dict[int, Any] = {}
+        self._spi_devs: Dict[Tuple[int, int], Any] = {}
+        self._uart_ports: Dict[str, Any] = {}
+
+        self._init_gpio_backend()
+
+    # -------------------------------------------------------------------------
+    # Board & Network Detection
+    # -------------------------------------------------------------------------
+    @staticmethod
+    def _detect_board() -> str:
+        model_paths = ["/proc/device-tree/model", "/sys/firmware/devicetree/base/model"]
+        for p in model_paths:
+            if os.path.exists(p):
+                try:
+                    with open(p, "rb") as f:
+                        model = f.read().decode("utf-8", errors="ignore").strip("\x00\r\n ").upper()
+                    if "UNO Q" in model or "ARDUINO UNO" in model:
+                        return "ARDUINO_UNO_Q"
+                    if "PORTENTA" in model or "X8" in model:
+                        return "PORTENTA_X8"
+                    if "RASPBERRY PI" in model:
+                        return "RASPBERRY_PI"
+                    if "JETSON" in model or "NVIDIA" in model:
+                        return "NVIDIA_JETSON"
+                    if model:
+                        return model.replace(" ", "_")[:24]
+                except Exception:
+                    pass
+
+        uname = platform.uname()
+        if uname.system == "Linux":
+            return f"LINUX_{uname.machine.upper()}"
+        return f"{uname.system.upper()}_{uname.machine.upper()}"
+
+    @staticmethod
+    def local_ip() -> str:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        try:
+            s.connect(("8.8.8.8", 80))
+            ip = s.getsockname()[0]
+        except Exception:
+            ip = "127.0.0.1"
+        finally:
+            s.close()
+        return ip
+
+    @classmethod
+    def broadcast_ip(cls) -> str:
+        ip = cls.local_ip()
+        parts = ip.split(".")
+        if len(parts) == 4 and parts[0] != "127":
+            return f"{parts[0]}.{parts[1]}.{parts[2]}.255"
+        return "255.255.255.255"
+
+    # -------------------------------------------------------------------------
+    # GPIO / PWM Backend Initialization (RPi.GPIO -> sysfs -> Virtual Sim)
+    # -------------------------------------------------------------------------
+    def _init_gpio_backend(self) -> None:
+        try:
+            import RPi.GPIO as GPIO  # type: ignore
+
+            GPIO.setwarnings(False)
+            GPIO.setmode(GPIO.BCM)
+            self._rpi_gpio = GPIO
+            self._gpio_backend = "rpi_gpio"
+            return
+        except Exception:
+            pass
+
+        if os.path.exists("/sys/class/gpio"):
+            self._gpio_backend = "sysfs"
+        else:
+            self._gpio_backend = "sim"
+
+    def setup_pin(self, pin: int, mode: str = "OUT", pullup: bool = False) -> None:
+        if pin < 0 or pin == 255:
+            return
+        if self._gpio_backend == "rpi_gpio" and self._rpi_gpio is not None:
+            if mode == "OUT":
+                self._rpi_gpio.setup(pin, self._rpi_gpio.OUT)
+                self._rpi_gpio.output(pin, self._rpi_gpio.LOW)
+            else:
+                pud = self._rpi_gpio.PUD_UP if pullup else self._rpi_gpio.PUD_OFF
+                self._rpi_gpio.setup(pin, self._rpi_gpio.IN, pull_up_down=pud)
+        elif self._gpio_backend == "sysfs":
+            gpio_dir = f"/sys/class/gpio/gpio{pin}"
+            if not os.path.exists(gpio_dir):
+                try:
+                    with open("/sys/class/gpio/export", "w") as f:
+                        f.write(str(pin))
+                except Exception:
+                    pass
+            try:
+                with open(f"{gpio_dir}/direction", "w") as f:
+                    f.write("out" if mode == "OUT" else "in")
+            except Exception:
+                pass
+        else:
+            self._sim_pins[pin] = 0
+
+    def digital_write(self, pin: int, value: int) -> None:
+        if pin < 0 or pin == 255:
+            return
+        v = 1 if value > 0 else 0
+        if self._gpio_backend == "rpi_gpio" and self._rpi_gpio is not None:
+            self._rpi_gpio.output(pin, self._rpi_gpio.HIGH if v else self._rpi_gpio.LOW)
+        elif self._gpio_backend == "sysfs":
+            try:
+                with open(f"/sys/class/gpio/gpio{pin}/value", "w") as f:
+                    f.write("1" if v else "0")
+            except Exception:
+                pass
+        else:
+            prev = self._sim_pins.get(pin)
+            self._sim_pins[pin] = v
+            if self.verbose_sim and prev != v:
+                print(f"  [LinuxHAL] GPIO Pin {pin} -> {'HIGH (1)' if v else 'LOW  (0)'}")
+
+    def digital_read(self, pin: int, pullup: bool = False) -> float:
+        if pin < 0 or pin == 255:
+            return 0.0
+        if self._gpio_backend == "rpi_gpio" and self._rpi_gpio is not None:
+            raw = int(self._rpi_gpio.input(pin))
+            return float(1 - raw if pullup else raw)
+        elif self._gpio_backend == "sysfs":
+            try:
+                with open(f"/sys/class/gpio/gpio{pin}/value", "r") as f:
+                    raw = int(f.read().strip())
+                return float(1 - raw if pullup else raw)
+            except Exception:
+                return 0.0
+        return float(self._sim_pins.get(pin, 0))
+
+    def pwm_write(self, pin: int, duty_255: int) -> None:
+        if pin < 0 or pin == 255:
+            return
+        d = max(0, min(255, int(duty_255)))
+        if self._gpio_backend == "rpi_gpio" and self._rpi_gpio is not None:
+            if pin not in self._pwm_instances:
+                self._rpi_gpio.setup(pin, self._rpi_gpio.OUT)
+                pwm = self._rpi_gpio.PWM(pin, 1000)
+                pwm.start(0)
+                self._pwm_instances[pin] = pwm
+            self._pwm_instances[pin].ChangeDutyCycle((d / 255.0) * 100.0)
+        else:
+            prev = self._sim_pins.get(pin)
+            self._sim_pins[pin] = d
+            if self.verbose_sim and prev != d:
+                print(f"  [LinuxHAL] PWM Pin {pin} -> duty {d}/255")
+
+    # -------------------------------------------------------------------------
+    # H-Bridge Motor Helpers
+    # -------------------------------------------------------------------------
+    def drive_hbridge_3pin(self, ena: int, in1: int, in2: int, speed: int) -> None:
+        s = max(-255, min(255, int(speed)))
+        if s > 0:
+            self.digital_write(in1, 1)
+            self.digital_write(in2, 0)
+            self.pwm_write(ena, s)
+        elif s < 0:
+            self.digital_write(in1, 0)
+            self.digital_write(in2, 1)
+            self.pwm_write(ena, -s)
+        else:
+            self.digital_write(in1, 0)
+            self.digital_write(in2, 0)
+            self.pwm_write(ena, 0)
+
+    def drive_hbridge_2pin(self, in1: int, in2: int, speed: int) -> None:
+        s = max(-255, min(255, int(speed)))
+        if s > 0:
+            self.pwm_write(in1, s)
+            self.pwm_write(in2, 0)
+        elif s < 0:
+            self.pwm_write(in1, 0)
+            self.pwm_write(in2, -s)
+        else:
+            self.pwm_write(in1, 0)
+            self.pwm_write(in2, 0)
+
+    # -------------------------------------------------------------------------
+    # I2C / SPI / UART Bus Helpers
+    # -------------------------------------------------------------------------
+    def _get_i2c(self, bus_num: int = 1):
+        if bus_num not in self._i2c_buses:
+            try:
+                import smbus2  # type: ignore
+
+                self._i2c_buses[bus_num] = smbus2.SMBus(bus_num)
+            except Exception:
+                self._i2c_buses[bus_num] = None
+        return self._i2c_buses[bus_num]
+
+    def i2c_write_reg(self, bus_num: int, i2c_addr: int, reg: int, val: int) -> None:
+        bus = self._get_i2c(bus_num)
+        if bus is not None:
+            try:
+                bus.write_byte_data(i2c_addr, reg & 0xFF, val & 0xFF)
+                return
+            except Exception:
+                pass
+        if self.verbose_sim:
+            print(f"  [LinuxHAL] I2C(bus={bus_num}, addr=0x{i2c_addr:02X}) write reg 0x{reg:02X} = 0x{val:02X}")
+
+    def i2c_read_bytes(self, bus_num: int, i2c_addr: int, reg: int, length: int) -> List[int]:
+        bus = self._get_i2c(bus_num)
+        if bus is not None:
+            try:
+                return list(bus.read_i2c_block_data(i2c_addr, reg & 0xFF, length))
+            except Exception:
+                pass
+        return [0] * length
+
+    def _get_uart(self, port_path: str, baud: int):
+        if port_path not in self._uart_ports:
+            try:
+                import serial  # type: ignore
+
+                self._uart_ports[port_path] = serial.Serial(port_path, baudrate=baud, timeout=0.01)
+            except Exception:
+                self._uart_ports[port_path] = None
+        return self._uart_ports[port_path]
+
+    def uart_write(self, port_path: str, baud: int, data_str: str, fallback_byte: int = 0) -> None:
+        ser = self._get_uart(port_path, baud)
+        if ser is not None:
+            try:
+                if data_str:
+                    ser.write((data_str + "\n").encode("utf-8"))
+                else:
+                    ser.write(bytes([fallback_byte & 0xFF]))
+                return
+            except Exception:
+                pass
+        if self.verbose_sim:
+            print(f"  [LinuxHAL] UART({port_path} @ {baud}) TX -> '{data_str or fallback_byte}'")
+
+    def uart_read_float(self, port_path: str, baud: int, last_val: float = 0.0) -> float:
+        ser = self._get_uart(port_path, baud)
+        if ser is not None and ser.in_waiting > 0:
+            try:
+                line = ser.readline().decode("utf-8", errors="ignore").strip()
+                if line:
+                    return float(line)
+            except Exception:
+                pass
+        return last_val
+
+    # -------------------------------------------------------------------------
+    # Built-in Linux System & Sensor Readers
+    # -------------------------------------------------------------------------
+    @staticmethod
+    def read_cpu_temp() -> float:
+        paths = [
+            "/sys/class/thermal/thermal_zone0/temp",
+            "/sys/devices/virtual/thermal/thermal_zone0/temp",
+        ]
+        for p in paths:
+            if os.path.exists(p):
+                try:
+                    with open(p, "r") as f:
+                        return float(f.read().strip()) / 1000.0
+                except Exception:
+                    pass
+        return 42.0
+
+    @staticmethod
+    def read_system_load() -> List[float]:
+        load_1m = 0.0
+        ram_pct = 0.0
+        if os.path.exists("/proc/loadavg"):
+            try:
+                with open("/proc/loadavg", "r") as f:
+                    load_1m = float(f.read().split()[0])
+            except Exception:
+                pass
+        if os.path.exists("/proc/meminfo"):
+            try:
+                mem: Dict[str, int] = {}
+                with open("/proc/meminfo", "r") as f:
+                    for line in f:
+                        parts = line.split(":")
+                        if len(parts) == 2:
+                            mem[parts[0].strip()] = int(parts[1].strip().split()[0])
+                total = mem.get("MemTotal", 0)
+                avail = mem.get("MemAvailable", mem.get("MemFree", 0))
+                if total > 0:
+                    ram_pct = ((total - avail) / float(total)) * 100.0
+            except Exception:
+                pass
+        return [round(load_1m, 2), round(ram_pct, 1)]
+
+    @staticmethod
+    def read_wifi_rssi() -> float:
+        if os.path.exists("/proc/net/wireless"):
+            try:
+                with open("/proc/net/wireless", "r") as f:
+                    lines = f.readlines()
+                if len(lines) >= 3:
+                    parts = lines[2].split()
+                    if len(parts) >= 4:
+                        val = float(parts[3].rstrip("."))
+                        return val if val < 0 else val - 100.0
+            except Exception:
+                pass
+        return -50.0
+
+    def read_ultrasonic(self, trig: int, echo: int) -> float:
+        if self._gpio_backend == "sim":
+            return 25.0
+        self.digital_write(trig, 0)
+        time.sleep(0.000002)
+        self.digital_write(trig, 1)
+        time.sleep(0.000010)
+        self.digital_write(trig, 0)
+
+        timeout = time.perf_counter() + 0.015
+        while self.digital_read(echo) == 0:
+            if time.perf_counter() > timeout:
+                return -1.0
+        start = time.perf_counter()
+        while self.digital_read(echo) == 1:
+            if time.perf_counter() > timeout:
+                return -1.0
+        duration_us = (time.perf_counter() - start) * 1_000_000.0
+        return round((duration_us * 0.0343) * 0.5, 2)
+
+    def read_mpu6050(self, bus_num: int, i2c_addr: int) -> List[float]:
+        raw = self.i2c_read_bytes(bus_num, i2c_addr, 0x3B, 14)
+        if any(raw):
+            ax, ay, az, _, gx, gy, gz = struct.unpack(">hhhhhhh", bytes(raw))
+            return [
+                round(ax / 16384.0, 2),
+                round(ay / 16384.0, 2),
+                round(az / 16384.0, 2),
+                round(gx / 131.0, 2),
+                round(gy / 131.0, 2),
+                round(gz / 131.0, 2),
+            ]
+        return [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]
+
+    def read_lsm6dsox(self, bus_num: int, i2c_addr: int) -> List[float]:
+        raw = self.i2c_read_bytes(bus_num, i2c_addr, 0x22, 12)
+        if any(raw):
+            gx, gy, gz, ax, ay, az = struct.unpack("<hhhhhh", bytes(raw))
+            return [
+                round(ax * 0.000061, 2),
+                round(ay * 0.000061, 2),
+                round(az * 0.000061, 2),
+                round(gx * 0.00875, 2),
+                round(gy * 0.00875, 2),
+                round(gz * 0.00875, 2),
+            ]
+        return [0.0, 0.0, 1.0, 0.0, 0.0, 0.0]

openswarm_slave/node.py

@@ -0,0 +1,411 @@
+"""
+SwarmNode (Linux Slave Agent)
+=============================
+Identical Hardware Declaration API & UDP Wire Protocol (4210 / 4211) to the C++ Arduino library.
+Supports both Pythonic `snake_case` and Arduino `camelCase` registration methods!
+"""
+
+import json
+import socket
+import threading
+import time
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .hal_linux import LinuxHAL
+
+SWARM_DEFAULT_PORT = 4210
+SWARM_DISCOVERY_PORT = 4211
+SWARM_WATCHDOG_SEC = 0.50   # 500ms hardware safety watchdog
+SWARM_TELEMETRY_SEC = 0.05  # 20 Hz sensor telemetry stream
+SWARM_HELLO_SEC = 1.00      # 1 Hz discovery broadcast
+
+
+class SwarmNode:
+    def __init__(self, node_id: str, udp_port: int = SWARM_DEFAULT_PORT, verbose_sim: bool = True):
+        self.node_id = node_id
+        self.udp_port = udp_port
+        self.hal = LinuxHAL(verbose_sim=verbose_sim)
+
+        self._actuators: Dict[str, Dict[str, Any]] = {}
+        self._sensors: Dict[str, Dict[str, Any]] = {}
+
+        self._master_addr: Optional[ tuple ] = None
+        self._last_master_pkt = 0.0
+        self._watchdog_tripped = False
+        self._start_time = time.time()
+        self._running = False
+        self._sock: Optional[socket.socket] = None
+
+    # -------------------------------------------------------------------------
+    # 1. Standard Actuator Registration API (Motors, Servos, Steppers, GPIO)
+    # -------------------------------------------------------------------------
+    def register_l298n(self, name: str, ena: int, in1: int, in2: int, enb: int, in3: int, in4: int) -> bool:
+        for p in (ena, in1, in2, enb, in3, in4):
+            self.hal.setup_pin(p, "OUT")
+        self._actuators[name] = {"type": "L298N", "pins": [ena, in1, in2, enb, in3, in4]}
+        return True
+
+    def register_drv8833(self, name: str, in1: int, in2: int, in3: int, in4: int) -> bool:
+        for p in (in1, in2, in3, in4):
+            self.hal.setup_pin(p, "OUT")
+        self._actuators[name] = {"type": "DRV8833", "pins": [in1, in2, in3, in4]}
+        return True
+
+    def register_motor_2pin(self, name: str, pin_a: int, pin_b: int) -> bool:
+        self.hal.setup_pin(pin_a, "OUT")
+        self.hal.setup_pin(pin_b, "OUT")
+        self._actuators[name] = {"type": "MOTOR_2PIN", "pins": [pin_a, pin_b]}
+        return True
+
+    def register_servo(self, name: str, pin: int) -> bool:
+        self.hal.setup_pin(pin, "OUT")
+        self._actuators[name] = {"type": "SERVO", "pins": [pin]}
+        return True
+
+    def register_stepper(self, name: str, step_pin: int, dir_pin: int, en_pin: int = 255) -> bool:
+        self.hal.setup_pin(step_pin, "OUT")
+        self.hal.setup_pin(dir_pin, "OUT")
+        if en_pin != 255:
+            self.hal.setup_pin(en_pin, "OUT")
+        self._actuators[name] = {"type": "STEPPER", "pins": [step_pin, dir_pin, en_pin]}
+        return True
+
+    def register_digital_output(self, name: str, pin: int) -> bool:
+        self.hal.setup_pin(pin, "OUT")
+        self._actuators[name] = {"type": "DIGITAL_OUT", "pins": [pin]}
+        return True
+
+    def register_pwm_output(self, name: str, pin: int) -> bool:
+        self.hal.setup_pin(pin, "OUT")
+        self._actuators[name] = {"type": "PWM_OUT", "pins": [pin]}
+        return True
+
+    def register_pin(self, name: str, pin: int, mode: str = "OUT", pullup: bool = False) -> bool:
+        if mode.upper().startswith("IN"):
+            return self.register_digital_input(name, pin, pullup=pullup)
+        return self.register_digital_output(name, pin)
+
+    # -------------------------------------------------------------------------
+    # 2. Standard Sensor Registration API
+    # -------------------------------------------------------------------------
+    def register_ultrasonic(self, name: str, trig_pin: int, echo_pin: int) -> bool:
+        self.hal.setup_pin(trig_pin, "OUT")
+        self.hal.setup_pin(echo_pin, "IN")
+        self._sensors[name] = {"type": "ULTRASONIC", "pins": [trig_pin, echo_pin]}
+        return True
+
+    def register_bumper(self, name: str, pin: int, pullup: bool = True) -> bool:
+        return self.register_digital_input(name, pin, pullup=pullup)
+
+    def register_ir_sensor(self, name: str, pin: int, pullup: bool = False) -> bool:
+        return self.register_digital_input(name, pin, pullup=pullup)
+
+    def register_digital_input(self, name: str, pin: int, pullup: bool = False) -> bool:
+        self.hal.setup_pin(pin, "IN", pullup=pullup)
+        self._sensors[name] = {"type": "DIGITAL_IN", "pins": [pin], "pullup": pullup}
+        return True
+
+    def register_mpu6050(self, name: str, i2c_addr: int = 0x68, bus_num: int = 1) -> bool:
+        self.hal.i2c_write_reg(bus_num, i2c_addr, 0x6B, 0x00)
+        self._sensors[name] = {"type": "MPU6050", "bus": bus_num, "addr": i2c_addr}
+        return True
+
+    def register_lsm6dsox(self, name: str, i2c_addr: int = 0x6A, bus_num: int = 1) -> bool:
+        self.hal.i2c_write_reg(bus_num, i2c_addr, 0x10, 0x40)
+        self.hal.i2c_write_reg(bus_num, i2c_addr, 0x11, 0x40)
+        self._sensors[name] = {"type": "LSM6DSOX", "bus": bus_num, "addr": i2c_addr}
+        return True
+
+    def register_cpu_temp(self, name: str = "cpu_temp") -> bool:
+        self._sensors[name] = {"type": "CPU_TEMP"}
+        return True
+
+    def register_system_load(self, name: str = "sys_load") -> bool:
+        self._sensors[name] = {"type": "SYS_LOAD"}
+        return True
+
+    def register_wifi_rssi(self, name: str = "rssi") -> bool:
+        self._sensors[name] = {"type": "WIFI_RSSI"}
+        return True
+
+    # -------------------------------------------------------------------------
+    # 3. Universal Bus Protocols & Custom Callbacks (I2C, SPI, UART, Custom)
+    # -------------------------------------------------------------------------
+    def register_generic_i2c(self, name: str, i2c_addr: int, reg_addr: int, num_bytes: int = 2, bus_num: int = 1) -> bool:
+        self._sensors[name] = {
+            "type": "GENERIC_I2C",
+            "bus": bus_num,
+            "addr": i2c_addr,
+            "reg": reg_addr,
+            "len": num_bytes,
+        }
+        return True
+
+    def register_i2c_actuator(self, name: str, i2c_addr: int, bus_num: int = 1) -> bool:
+        self._actuators[name] = {"type": "I2C_BUS", "bus": bus_num, "addr": i2c_addr}
+        return True
+
+    def register_uart_sensor(self, name: str, port: str = "/dev/ttyUSB0", baud: int = 9600) -> bool:
+        self._sensors[name] = {"type": "UART_BUS", "port": port, "baud": baud, "last": 0.0}
+        return True
+
+    def register_uart_actuator(self, name: str, port: str = "/dev/ttyUSB0", baud: int = 9600) -> bool:
+        self._actuators[name] = {"type": "UART_BUS", "port": port, "baud": baud}
+        return True
+
+    def register_custom_sensor(self, name: str, read_callback: Callable[[], Union[float, List[float]]]) -> bool:
+        self._sensors[name] = {"type": "CUSTOM", "fn": read_callback}
+        return True
+
+    def register_custom_actuator(self, name: str, write_callback: Callable[[int, int, str], None]) -> bool:
+        self._actuators[name] = {"type": "CUSTOM", "fn": write_callback}
+        return True
+
+    # -------------------------------------------------------------------------
+    # Arduino C++ camelCase Aliases (So sketches translate 1:1!)
+    # -------------------------------------------------------------------------
+    registerL298N = register_l298n
+    registerDRV8833 = register_drv8833
+    registerMotor2Pin = register_motor_2pin
+    registerServo = register_servo
+    registerStepper = register_stepper
+    registerDigitalOutput = register_digital_output
+    registerPWMOutput = register_pwm_output
+    registerPin = register_pin
+    registerUltrasonic = register_ultrasonic
+    registerBumper = register_bumper
+    registerIRSensor = register_ir_sensor
+    registerDigitalInput = register_digital_input
+    registerMPU6050 = register_mpu6050
+    registerLSM6DSOX = register_lsm6dsox
+    registerWiFiRSSI = register_wifi_rssi
+    registerGenericI2C = register_generic_i2c
+    registerI2CActuator = register_i2c_actuator
+    registerUARTSensor = register_uart_sensor
+    registerUARTActuator = register_uart_actuator
+    registerCustomSensor = register_custom_sensor
+    registerCustomActuator = register_custom_actuator
+
+    # -------------------------------------------------------------------------
+    # 4. Start Background Daemon
+    # -------------------------------------------------------------------------
+    def start(self, block: bool = True) -> None:
+        self._sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        if hasattr(socket, "SO_BROADCAST"):
+            self._sock.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, 1)
+        self._sock.bind(("0.0.0.0", self.udp_port))
+        self._sock.settimeout(0.01)
+
+        self._running = True
+        self._last_master_pkt = time.time()
+
+        ip = self.hal.local_ip()
+        print("==========================================================")
+        print(f" OpenSwarm Linux Slave Node : '{self.node_id}'")
+        print(f" Detected Platform          : {self.hal.board_name} (GPIO: {self.hal._gpio_backend})")
+        print(f" Local IP & UDP Port        : {ip}:{self.udp_port}")
+        print(f" Registered Actuators       : {list(self._actuators.keys())}")
+        print(f" Registered Sensors         : {list(self._sensors.keys())}")
+        print(" Advertising to Linux Master on UDP Port 4211...")
+        print("==========================================================")
+
+        daemon = threading.Thread(target=self._background_loop, daemon=True, name="SwarmLinuxSlave")
+        daemon.start()
+
+        if block:
+            try:
+                while self._running:
+                    time.sleep(0.5)
+            except KeyboardInterrupt:
+                print("\n[SwarmNode] Stopping motors and shutting down Linux Slave...")
+                self.stop()
+
+    def stop(self) -> None:
+        self._running = False
+        self._emergency_stop_all()
+        if self._sock:
+            try:
+                self._sock.close()
+            except Exception:
+                pass
+
+    # -------------------------------------------------------------------------
+    # Core Runtime Loop (Discovery, Telemetry, Command Execution, Watchdog)
+    # -------------------------------------------------------------------------
+    def _background_loop(self) -> None:
+        last_telemetry = 0.0
+        last_hello = 0.0
+
+        while self._running:
+            now = time.time()
+
+            # 1. Handle Incoming Master Commands
+            self._handle_incoming()
+
+            # 2. 500ms Hardware Safety Watchdog
+            if self._master_addr is not None and (now - self._last_master_pkt > SWARM_WATCHDOG_SEC):
+                if not self._watchdog_tripped:
+                    self._emergency_stop_all()
+                    self._watchdog_tripped = True
+                    print("[SwarmNode] WATCHDOG: Master timeout -> Motors stopped.")
+
+            # 3. 20 Hz Sensor Telemetry Stream
+            if self._master_addr is not None and (now - last_telemetry >= SWARM_TELEMETRY_SEC):
+                last_telemetry = now
+                self._send_telemetry()
+
+            # 4. 1 Hz Auto-Discovery Broadcast
+            if now - last_hello >= SWARM_HELLO_SEC:
+                last_hello = now
+                self._send_hello()
+
+    def _handle_incoming(self) -> None:
+        if not self._sock:
+            return
+        try:
+            data, addr = self._sock.recvfrom(1024)
+        except socket.timeout:
+            return
+        except OSError:
+            return
+
+        try:
+            msg = json.loads(data.decode("utf-8", errors="ignore"))
+        except Exception:
+            return
+
+        cmd = msg.get("cmd")
+        if not cmd:
+            return
+
+        self._master_addr = addr
+        self._last_master_pkt = time.time()
+        self._watchdog_tripped = False
+
+        if cmd == "PING":
+            self._send_telemetry()
+        elif cmd == "STOP":
+            self._emergency_stop_all()
+        elif cmd == "PIN":
+            pin = int(msg.get("pin", -1))
+            val = int(msg.get("value", 0))
+            pwm = int(msg.get("pwm", 0))
+            if pin >= 0:
+                if pwm > 0:
+                    self.hal.pwm_write(pin, val)
+                else:
+                    self.hal.setup_pin(pin, "OUT")
+                    self.hal.digital_write(pin, val)
+        elif cmd == "ACT":
+            name = msg.get("name", "")
+            act = self._actuators.get(name)
+            if not act:
+                return
+
+            v1 = int(
+                msg.get(
+                    "value",
+                    msg.get(
+                        "state",
+                        msg.get("left", msg.get("angle", msg.get("steps", msg.get("reg", msg.get("v1", 0))))),
+                    ),
+                )
+            )
+            v2 = int(msg.get("right", msg.get("val", msg.get("v2", 0))))
+            data_str = str(msg.get("data", ""))
+            self._execute_actuator(act, v1, v2, data_str)
+
+    def _execute_actuator(self, act: Dict[str, Any], v1: int, v2: int, data_str: str) -> None:
+        t = act["type"]
+        pins = act.get("pins", [])
+        if t == "L298N":
+            self.hal.drive_hbridge_3pin(pins[0], pins[1], pins[2], v1)
+            self.hal.drive_hbridge_3pin(pins[3], pins[4], pins[5], v2)
+        elif t == "DRV8833":
+            self.hal.drive_hbridge_2pin(pins[0], pins[1], v1)
+            self.hal.drive_hbridge_2pin(pins[2], pins[3], v2)
+        elif t == "MOTOR_2PIN":
+            self.hal.drive_hbridge_2pin(pins[0], pins[1], v1)
+        elif t == "DIGITAL_OUT":
+            self.hal.digital_write(pins[0], 1 if v1 > 0 else 0)
+        elif t == "PWM_OUT" or t == "SERVO":
+            self.hal.pwm_write(pins[0], v1)
+        elif t == "I2C_BUS":
+            self.hal.i2c_write_reg(act["bus"], act["addr"], v1, v2)
+        elif t == "UART_BUS":
+            self.hal.uart_write(act["port"], act["baud"], data_str, v1)
+        elif t == "CUSTOM":
+            act["fn"](v1, v2, data_str)
+
+    def _read_sensor(self, sens: Dict[str, Any]) -> Union[float, List[float]]:
+        t = sens["type"]
+        if t == "CPU_TEMP":
+            return self.hal.read_cpu_temp()
+        if t == "SYS_LOAD":
+            return self.hal.read_system_load()
+        if t == "WIFI_RSSI":
+            return self.hal.read_wifi_rssi()
+        if t == "DIGITAL_IN":
+            return self.hal.digital_read(sens["pins"][0], sens.get("pullup", False))
+        if t == "ULTRASONIC":
+            return self.hal.read_ultrasonic(sens["pins"][0], sens["pins"][1])
+        if t == "MPU6050":
+            return self.hal.read_mpu6050(sens["bus"], sens["addr"])
+        if t == "LSM6DSOX":
+            return self.hal.read_lsm6dsox(sens["bus"], sens["addr"])
+        if t == "GENERIC_I2C":
+            raw = self.hal.i2c_read_bytes(sens["bus"], sens["addr"], sens["reg"], sens["len"])
+            val = 0
+            for b in raw:
+                val = (val << 8) | b
+            return float(val)
+        if t == "UART_BUS":
+            sens["last"] = self.hal.uart_read_float(sens["port"], sens["baud"], sens.get("last", 0.0))
+            return sens["last"]
+        if t == "CUSTOM":
+            return sens["fn"]()
+        return 0.0
+
+    def _send_hello(self) -> None:
+        if not self._sock:
+            return
+        payload = {
+            "type": "HELLO",
+            "node": self.node_id,
+            "board": self.hal.board_name,
+            "ip": self.hal.local_ip(),
+            "port": self.udp_port,
+            "actuators": list(self._actuators.keys()),
+            "sensors": list(self._sensors.keys()),
+        }
+        raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        try:
+            self._sock.sendto(raw, (self.hal.broadcast_ip(), SWARM_DISCOVERY_PORT))
+        except Exception:
+            pass
+
+    def _send_telemetry(self) -> None:
+        if not self._sock or self._master_addr is None:
+            return
+        uptime_ms = int((time.time() - self._start_time) * 1000)
+        sensor_readings: Dict[str, Any] = {}
+        for name, sens in self._sensors.items():
+            sensor_readings[name] = self._read_sensor(sens)
+
+        payload = {
+            "type": "STATE",
+            "node": self.node_id,
+            "uptime_ms": uptime_ms,
+            "sensors": sensor_readings,
+        }
+        raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+        try:
+            self._sock.sendto(raw, self._master_addr)
+        except Exception:
+            pass
+
+    def _emergency_stop_all(self) -> None:
+        for act in self._actuators.values():
+            if act["type"] in ("L298N", "DRV8833", "MOTOR_2PIN", "STEPPER"):
+                self._execute_actuator(act, 0, 0, "")

openswarm_slave-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: openswarm-slave
+Version: 0.1.0
+Summary: Zero-Control-Logic Linux Slave Agent for the OpenSwarm Robotics Framework (Arduino UNO Q, Portenta X8, Raspberry Pi, Jetson, Linux PC)
+Author-email: Mohammed Raihan Soniwala <raihann.eu@gmail.com>
+License: MIT
+Keywords: robotics,swarm-robotics,raspberry-pi,portenta-x8,arduino-uno-q,jetson,linux,hal
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: hardware
+Requires-Dist: pyserial>=3.5; extra == "hardware"
+Requires-Dist: smbus2>=0.4.2; extra == "hardware"
+Requires-Dist: spidev>=3.6; platform_system == "Linux" and extra == "hardware"
+Requires-Dist: gpiod>=2.0; platform_system == "Linux" and extra == "hardware"
+Dynamic: license-file
+
+# OpenSwarm Linux Slave Agent (`openswarm-slave`)
+
+Turns any Linux SBC (**Arduino UNO Q**, **Arduino Portenta X8**, **Raspberry Pi**, **Nvidia Jetson**) or **Linux Laptop** into a **Zero-Control-Logic OpenSwarm Slave Node**.
+
+Speaks the **exact same UDP protocol (`4210` / `4211`)** as the `SwarmNode` C++ microcontroller library—so the Central Linux Master (`openswarm-master`) controls ESP32s, RP2040s, Portenta X8s, Arduino UNO Qs, and Raspberry Pis through one unified API!
+
+---
+
+## 1. Installation (On Arduino UNO Q, Portenta X8, Raspberry Pi, or Linux Laptop)
+
+```bash
+# Option A: Install directly from official PyPI:
+pip install openswarm-slave
+
+# Option B: Clone and install locally for development:
+git clone https://github.com/raihhann/OpenSwarm.git
+cd OpenSwarm/slaves/linux
+pip install -e .
+```
+
+---
+
+## 2. Instant Terminal Launch (`openswarm-slave` CLI)
+
+You can turn any Linux machine into an active Slave node with a single command:
+
+```bash
+openswarm-slave --id portenta_x8 --led-pin 2
+```
+
+Then from your Master terminal (or another terminal on the same laptop!), test it immediately using `openswarm-master`:
+
+```bash
+openswarm scan
+openswarm blink portenta_x8 --ip 127.0.0.1
+```
+
+---
+
+## 3. Declarative Python Slave Script (`linux_slave_node.py`)
+
+Just like `void setup()` on the microcontroller, you **only declare attached pins and sensors** (supports both `snake_case` and Arduino `camelCase` methods):
+
+```python
+from openswarm_slave import SwarmNode
+
+node = SwarmNode("uno_q_node")
+
+# Declare attached hardware ONLY — Zero Control Logic!
+node.register_digital_output("led", 2)
+node.register_l298n("drive", 14, 27, 26, 32, 25, 33)
+node.register_ultrasonic("front_sonar", 5, 18)
+node.register_cpu_temp("cpu_temp")
+node.register_system_load("sys_load")
+node.register_wifi_rssi("rssi")
+
+# Start background daemon (500ms safety watchdog + 20Hz telemetry)
+node.start()
+```
+
+---
+
+## 4. Supported Linux Hardware Backends
+* **GPIO & PWM:** Automatically uses `RPi.GPIO` (on Raspberry Pi), Linux kernel `/sys/class/gpio` (on **Portenta X8**, **Arduino UNO Q**, **Jetson**), or **Virtual GPIO Simulation Mode** when testing on a standard Linux/Windows laptop.
+* **Buses (`I2C`, `SPI`, `UART`):** Supports `/dev/i2c-*` (`register_mpu6050`, `register_lsm6dsox`, `register_generic_i2c`, `register_i2c_actuator`) and `/dev/tty*` (`register_uart_sensor`, `register_uart_actuator`).
+* **Linux System Telemetry:** `register_cpu_temp()` (`°C`), `register_system_load()` (`[load_1m, ram_%]`), and `register_wifi_rssi()` (`dBm`).

openswarm_slave-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+openswarm_slave/__init__.py,sha256=HxGdiqQrG_Q4C5lRKthViW1KmPjwzVoMfRQHSJ29j-k,403
+openswarm_slave/cli.py,sha256=-e0xDmLJPU598i7sYn-JcMcn_MmZrCKp9N9MGYa5N9c,960
+openswarm_slave/hal_linux.py,sha256=nf5r717RPHWDUXkKHSYRMwalg8hPoPlLxTNHPlPS5T0,14764
+openswarm_slave/node.py,sha256=ep8tKBDIUtkXh9ESU3sKzxksPRuh2NVmkzgc1--rdaw,16904
+openswarm_slave-0.1.0.dist-info/licenses/LICENSE,sha256=AZ9akQ6SlsVf50LtUBr5TWjE-DqqK0JcgRZfdHmhscs,1081
+openswarm_slave-0.1.0.dist-info/METADATA,sha256=HCbk9IxirHaEEq8a1BE9PtPz2iEcF1O6SuEZa1VpC-E,3379
+openswarm_slave-0.1.0.dist-info/WHEEL,sha256=0CuiUZ_p9E4cD6NyLD6UG80LBXYyiSYZOKDm5lp32xk,91
+openswarm_slave-0.1.0.dist-info/entry_points.txt,sha256=KJsb_NJ4RRv1xcYa5V8KlJRZKlGosi4lxkWyDrvTsNE,61
+openswarm_slave-0.1.0.dist-info/top_level.txt,sha256=BO9SyiyjXpynj5n5kSC9OACVBhVc-2EOgKXHsR4vEqQ,16
+openswarm_slave-0.1.0.dist-info/RECORD,,

openswarm_slave-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.3.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

openswarm_slave-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openswarm-slave = openswarm_slave.cli:main

openswarm_slave-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Raihan Soniwala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openswarm_slave-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openswarm_slave