hilsim 0.1.0__py3-none-any.whl

hilsim/cli/commands.py

@@ -0,0 +1,20 @@
+import click
+from hilsim.scaffold.engine import scaffold_project
+
+@click.group()
+def cli():
+    """hilsim: hardware-in-the-loop simulation framework"""
+    pass
+
+@cli.command()
+@click.argument("project_name")
+def create(project_name): 
+    """Scaffold a new hilsim project in the current directory"""
+    click.echo(f"Creating project '{project_name}'...")
+    try: 
+        scaffold_project(project_name)
+        click.echo(f"Project '{project_name}' created successfully")
+    except FileExistsError:
+        """Note: engine won't create a project that already exists
+        (i.e. has the same name)"""
+        click.echo(f"Error: directory '{project_name}' already exists", err=True)

hilsim/core/actuators.py

@@ -0,0 +1,150 @@
+"""Define a world state class that serves as truth for all system variables"""
+
+import inspect
+import logging
+from random import gauss, random, uniform
+from typing import Any
+
+from hilsim.core.controls import Controls
+from hilsim.core.world_state import WorldState
+
+logger = logging.getLogger(__name__)
+#---------------------------------------------------------------------------------------
+class ActuatorBase:
+    """Actuator Base Class to enforce actuator class standards"""
+
+    registry: dict[str, Any] = {}
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        ActuatorBase.registry[cls.__name__] = cls
+
+    def __init__(
+        self, actuator_config: dict, world_state: WorldState, controller: Controls
+    ) -> None:
+        self.dt: float = 0.0
+        self.cst: float  = 0.0
+        self.time = world_state.state["time"]
+        self.world_state = world_state
+        self.failure_sim = actuator_config["failure_sim"]
+        self.settings = actuator_config["settings"]
+        self.effects = actuator_config["effects"]
+        self.sim = actuator_config["settings"]["sim"]
+        self.commanded_state = actuator_config["settings"]["initial_state"]
+        self.hardware_state = actuator_config["settings"]["initial_state"]
+        self.name = actuator_config["settings"]["name"]
+        self._stuck_counter: int = 0
+        self._transition_state: str = "settled"
+        self._stuck: bool = False
+        self._latency_remaining: float = 0.0
+        self._discover_effects()
+        self._controller = controller
+
+    def send_command(self, target_state: str, advanced_connection: bool = True) -> dict[str,bool]:
+        """Send command to microcontroller for target_state"""
+        device_name = self.settings["device"]
+        logger.info("Command triggered for %s, sending command to %s", self.name, device_name)
+        logger.info("Command has target_state: %s", target_state)
+        package = self.build_command(target_state)
+        if advanced_connection:
+            confirmation = self._controller.advanced_send(device_name, package)
+        else:
+            confirmation = self._controller.send(device_name, package)
+
+        self._update_commanded_state(confirmation, target_state)
+        return confirmation
+
+    def _update_commanded_state(self, confirmation: dict[str, bool], commanded_state: str) -> None:
+        """Update the commanded state attribute"""
+        if confirmation["confirmed"]:
+            self.commanded_state = commanded_state
+            self._transition_state = "commanded"
+
+    def _resolve_state_transition(self) -> None:
+        """Determine latency and encode failure mode of hardware (i.e. actuator is stuck)"""
+        if self._stuck and self._stuck_counter == 0:
+            self._stuck_counter += 1 
+            logger.critical("%s is stuck in state %s.", self.name, self.hardware_state)
+
+        if not self._stuck:
+            self._stuck_counter = 0
+
+        if self._transition_state == "settled":
+            return
+
+        if self._transition_state == "commanded":
+            self._latency_remaining = self._sample_latency()
+            self._stuck = self._sample_stuck()
+            self._transition_state = "pending_latency"
+
+        if self._transition_state == "pending_latency":
+            self._latency_remaining -= self.dt
+            if self._latency_remaining <= 0:
+                if self._stuck:
+                    self._transition_state = "stuck"
+                    logger.critical("%s is stuck", self.name)
+                else:
+                    self._transition_state = "settled"
+                    self.hardware_state = self.commanded_state
+                    self.cst = 0
+
+    def _sample_latency(self) -> float:
+        """Sample latency in milliseconds
+        Note, all values divided by 1000 to convert millesconds to seconds to
+        reflect the standard of self._dt"""
+
+        dist_type = self.failure_sim["cta_latency"]["distribution"]
+        if dist_type == "normal":
+            mean_val = self.failure_sim["cta_latency"]["mean"] / 1000
+            std_val = self.failure_sim["cta_latency"]["std"] / 1000
+            return max(0, gauss(mean_val, std_val))
+
+        if dist_type == "uniform":
+            max_lat = self.failure_sim["cta_latency"]["max"] / 1000
+            min_lat = self.failure_sim["cta_latency"]["min"] / 1000
+            return uniform(min_lat, max_lat)
+
+        # Could raise an error here sense dist_type would be unknown
+        # sorta a silent failure right now
+        logger.warning("Unknown distribution type: %s. Setting latency to zero", dist_type)
+        return 0
+
+    def _sample_stuck(self) -> bool:
+        "Determine if in this sim case the actuator gets stuck in its current state"
+        if random() <= self.failure_sim["stuck_probability"]:
+            return True
+        return False
+
+    def update(self, dt: float) -> None:
+        """Update world state based on commands, actuator latency, and effects"""
+        self.cst += dt
+        self.dt = dt
+        if self.sim:
+            self._resolve_state_transition()
+            self._apply_effects()
+
+    def _discover_effects(self):
+        """Find developer effects"""
+        self._effect_methods = {
+            name.replace("effect_", ""): method
+            for name, method in inspect.getmembers(self, predicate=inspect.ismethod)
+            if name.startswith("effect_")
+        }
+
+    def _apply_effects(self) -> None:
+        """Apply developer defined effects"""
+        for variable_name, method in self._effect_methods.items():
+            magnitude = method()
+            memory_type = self._get_memory_type(variable_name)
+
+            if "p" in memory_type:
+                self.world_state.apply_delta(variable_name, magnitude)
+            else:
+                self.world_state.add_contributions(variable_name, self.name, magnitude)
+
+    def _get_memory_type(self, variable_name: str) -> str:
+        """Get the memory type of an actuator-effected variable"""
+        return self.effects[variable_name]["effect_types"]
+
+#---------------------------------------------------------------------------------------
+

hilsim/core/builders.py

@@ -0,0 +1,115 @@
+"""Build instances of actuators, sensors, and set up device connections"""
+
+import importlib
+import logging
+from pathlib import Path
+
+from hilsim.core.actuators import ActuatorBase
+from hilsim.core.controls import (AdvancedCommunication, Controls,
+                                      SerialInterface)
+from hilsim.core.device_exceptions import DeviceConnectionError
+from hilsim.core.i2c_bus import I2CBus
+from hilsim.core.load_toml import LoadTOML
+from hilsim.core.sensors import DriverBase, SensorBase
+from hilsim.core.world_state import WorldState
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------------------
+
+class BuildComponents:
+    """Build instances of actuators, sensors, and set up device connections"""
+
+    def __init__(self, build_ctx: dict) -> None:
+        self.sensor_config = build_ctx["sensor_config"]
+        self.device_config = build_ctx["device_config"]
+        self.actuator_config = build_ctx["actuator_config"]
+        self.world_state = build_ctx["world_state"]
+        self.i2c_bus = build_ctx["i2c_bus"]
+        self.project_root = build_ctx["project_root"]
+        self._auto_discover(
+            self.project_root / "sensors"
+        )  # Populates SensorBase.registry and DriverBase.Registry
+        self._auto_discover(
+            self.project_root / "actuators"
+        )  # Populates ActuatorBase.registry
+
+    def _auto_discover(self, directory: str) -> None:
+        """Import all modules in a directory to trigger the __init_subclass__ registration"""
+        path = Path(directory)
+        for module_file in path.glob("*.py"):
+            if module_file.name.startswith("_"):
+                continue
+            module_name = module_file.stem
+            try:
+                spec = importlib.util.spec_from_file_location(module_name, module_file)
+                module = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(module)
+            except Exception as e:
+                raise ImportError(f"failed to load module '{module_file}': {e}") from e
+
+    def _build_actuators(self) -> dict:
+        """Create dictonary of instances of each actuator"""
+        actuators = {}
+        for name, config in self.actuator_config.items():
+            driver_name = config["settings"]["driver"]
+            driver_class = ActuatorBase.registry[driver_name]
+            actuators[name] = driver_class(config, self.world_state, self.controller)
+
+        return actuators
+
+    def _build_fake_sensors_with_drivers(self):
+        """Construct instances of drivers"""
+        drivers = {}
+        for sensor in self.sensor_config["sensor_params"]["enabled_sensors"]:
+
+            # Query important parameters
+            sensor_config = self.sensor_config["sensors"][sensor]
+            fake_sensor_name = sensor_config["fake_sensor_name"]
+            driver_name = sensor_config["driver_name"]
+
+            # Create instance of fake sensor
+            fake_sensor_class = SensorBase.registry[fake_sensor_name]
+            fake_sensor = fake_sensor_class(sensor_config, self.world_state)
+
+            # Create instance of driver
+            driver_class = DriverBase.registry[driver_name]
+            drivers[sensor] = driver_class(
+                sensor, sensor_config, self.i2c_bus, fake_sensor
+            )
+            logger.info("Registered %s → %s", sensor, driver_class.__name__)
+
+        return drivers
+
+    def _build_devices(self) -> dict:
+        """Build peripherial devices and open serial connections to them"""
+        device_configs = self.device_config["devices"]
+        advanced_comms_config = self.device_config["advanced_communication"]
+        logger.info("building peripherial microcontrollers")
+
+        device_dict = {}
+        for device in self.device_config["enabled_devices"]:
+            sub_config = device_configs[device]
+            device_comms = SerialInterface(sub_config, device)
+            device_w_advanced_comms = AdvancedCommunication(
+                sub_config, advanced_comms_config, device_comms
+            )
+            connected = device_w_advanced_comms.device.connect()
+            if not connected:
+                logger.error("Error connecting to %s", device)
+                raise DeviceConnectionError(
+                    device, "Failed to connect to device. See message logs."
+                )
+            logger.info("successfully connected to %s", device)
+            device_dict[device] = device_w_advanced_comms
+        return device_dict
+
+    def build_all(self) -> dict:
+        """Build all sensors, devices, and actuators"""
+        self.controller = Controls(self._build_devices()) # actuators depend on the Controller!
+        actuators = self._build_actuators()
+        sensors = self._build_fake_sensors_with_drivers()
+        return {"actuators": actuators, "sensors": sensors}
+
+
+# ---------------------------------------------------------------------------------------

hilsim/core/controls.py

@@ -0,0 +1,351 @@
+"""Holds the relevant classes for controls handling including:
+- RP2040Communication
+- RP2040AdvancedErrorHandling
+- Controls"""
+
+import logging
+import os
+import time
+from abc import ABC, abstractmethod
+from datetime import datetime, timedelta
+from pathlib import Path
+from random import random
+
+import serial
+from serial import SerialException
+
+from hilsim.core.device_exceptions import DeviceConnectionError
+from hilsim.core.load_toml import LoadTOML
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------------------
+class FakeSerial:
+    """Fake Serial class that holds the methods of serial.Serial relevant to
+    the CommunicationInterface class"""
+
+    def __init__(
+        self, super_sim_fr: float | int, read_time: float, hb_sm: str, hb_rm: str
+    ) -> None:
+        self.failure_rate = super_sim_fr
+        self.read_time = read_time
+        self.hb_send_msg = hb_sm
+        self.hb_receive_msg = hb_rm
+        self.msg = "".encode()
+        self.return_msg: bytes
+
+    def write(self, msg: bytes) -> None:
+        """Write a message (doesn't really do much in since this is fake)"""
+        self.msg = msg
+
+    def readline(self) -> bytes:
+        """Return bytes and an expected response"""
+        # multiplied by 0.7 to help deal with timing uncertainty in non-RTOS
+        confirm_wait = random() * self.read_time * 0.7
+        start_time = datetime.now()
+        if random() < self.failure_rate:
+            # Don't respond right away as if you do this leads to a huge 
+            # concatenation issue for an error string and takes forever.
+            time.sleep(self.read_time * 0.25)
+            return "".encode()
+        if self.hb_send_msg.encode() in self.msg:
+            self.return_msg = self.hb_receive_msg.encode()
+        else:
+            self.return_msg = self.msg
+        while True:
+            current_td = datetime.now() - start_time
+            if current_td >= timedelta(seconds=confirm_wait):
+                return self.return_msg
+
+    def close(self) -> None:
+        """fake closing the serial port—doesn't actually do anything in sim"""
+
+
+# ---------------------------------------------------------------------------------------
+class CommunicationInterface(ABC):
+    """Define abstract communication interface for serial connections"""
+
+    def __init__(self, config_dict: dict, device_name: str) -> None:
+        self.sim: bool = config_dict["sim"]
+        self.super_sim: bool = config_dict["super_sim"]
+        self.super_sim_fr: bool = config_dict["super_sim_fr"]
+        self.baud_rate = int(config_dict["baud_rate"])
+        self.device_id: str = config_dict["device_ID"]
+        self.fake_device_id: str = config_dict["fake_device_ID"]
+        self.time_out = float(config_dict["time_out"])
+        self.read_time = float(config_dict["read_time"])
+        self.hb_sm: str = config_dict["hb_send_msg"]
+        self.hb_rm: str = config_dict["hb_receive_msg"]
+        self.pca = True
+        self.connected = False
+        self.ser: serial.Serial | FakeSerial
+        self.device_name = device_name
+
+    @abstractmethod
+    def connect(self) -> bool:
+        """Enforce a connect method"""
+
+    @abstractmethod
+    def disconnect(self) -> None:
+        """Enforce a disconnect method"""
+
+    @abstractmethod
+    def read_and_write(
+        self,
+        send_msg: str,
+        receive_msg: str,
+    ) -> bool:
+        """Enforce a read and write method"""
+
+
+# ---------------------------------------------------------------------------------------
+class SerialInterface(CommunicationInterface):
+    """Directly communicate with an serial interface Chip over serial connection (usb)"""
+
+    def __init__(self, config_dict: dict, device_name: str) -> None:
+        logger.info("Creating %s", device_name)
+        super().__init__(config_dict, device_name)
+
+    def connect(self) -> bool:
+        """create the serial connection"""
+        logger.info("Initalizing serial connection for %s", self.device_name)
+        if not self.super_sim:
+            if self.sim:
+                device_id = self.fake_device_id
+            else:
+                device_id = self.device_id
+
+            try:
+                self.ser = serial.Serial(
+                    port=device_id, baudrate=self.baud_rate, timeout=self.time_out
+                )
+                self.connected = True
+                return True
+            except SerialException as e:
+                logger.error(
+                    "Error initializing serial connection to %s: %s",
+                    self.device_name,
+                    str(e),
+                )
+                return False
+        else:
+            self.ser = FakeSerial(
+                self.super_sim_fr, self.read_time, self.hb_sm, self.hb_rm
+            )
+            self.connected = True
+            return True
+
+    def disconnect(self) -> None:
+        """Disconnect from the serial port"""
+        try:
+            logger.info("Closing the serial port to %s", self.device_name)
+            self.ser.close()
+            self.connected = False
+            logger.info("Successfully closed the connection to %s", self.device_name)
+        except SerialException as e:
+            logger.error("Could not close serial port to %s: %s", self.device_name, e)
+
+    def read_and_write(self, send_msg: str, receive_msg: str) -> bool:
+        """Read and write over the serial connection"""
+        try:
+            received_data = []
+            logger.info("sending message '%s' to %s", send_msg, self.device_name)
+            self.ser.write(send_msg.encode())
+            start_time = datetime.now()
+            while datetime.now() - start_time < timedelta(seconds=self.read_time):
+                line = self.ser.readline().decode().strip()
+                received_data.append(line)
+                if receive_msg in line:
+                    logger.info("received correct confirmation: '%s'", line)
+                    return True
+
+            received_data_str = " ".join(received_data)
+
+            logger.error(
+                "Command '%s' sent to %s but no/incorrect confirmation: '%s'",
+                send_msg,
+                self.device_name,
+                received_data_str,
+            )
+            return False
+
+        except SerialException as e:
+            msg = f"Error writing to the serial port for {self.device_name}: {e}"
+            logger.error(msg)
+            return False
+
+
+# ---------------------------------------------------------------------------------------
+class AdvancedCommunication:
+    """Check and handle communication with the a device that is a communication
+    interface"""
+
+    def __init__(self, config_dict: dict, ac_dict: dict, device: CommunicationInterface) -> None:
+        self.retries = int(ac_dict["retries"])
+        self.connection_cycles = int(ac_dict["connection_cycles"])
+        self.power_cycles = int(ac_dict["power_cycles"])
+        self.hb_sm = config_dict["hb_send_msg"]
+        self.hb_rm = config_dict["hb_receive_msg"]
+        self.device = device
+        self.device_name = device.device_name
+
+    def __repr__(self):
+        return f"Instance of AdvancedCommunication for {self.device_name}"
+
+    def send(self, send_msg: str, receive_msg: str, secondary_send=False) -> bool:
+        """Send the initial command and check for response"""
+        logger.info(
+            "Will send '%s' to %s, expecting '%s' in return for confirmation",
+            send_msg,
+            self.device_name,
+            receive_msg,
+        )
+        result = self.device.read_and_write(send_msg, receive_msg)
+        if not result and not secondary_send:
+            logger.info("Continuing to connection recovery")
+        if not result and secondary_send:
+            logger.info(
+                "connection was recovered with heartbeat, but failed on \
+                a secondary send of command '%s'. No further \
+                recovery for this command until called again.",
+                send_msg,
+            )
+        return result
+
+    def _retries(self, send_msg: str, receive_msg: str) -> bool:
+        """retry sending the message to determine if error is transient"""
+
+        for i in range(self.retries):
+            logger.info("attempting retry %s", str(i + 1))
+            confirmed = self.device.read_and_write(send_msg, receive_msg)
+            if confirmed:
+                logger.info(
+                    "received correct response on retry %s, %s connection re-established.",
+                    str(i + 1),
+                    self.device_name,
+                )
+                return True
+
+        logger.info("Max retries hit")
+        return False
+
+    def _software_cycle(self) -> bool:
+        """drop and reinitialize serial connection, check with heart beat"""
+        for i in range(self.connection_cycles):
+            logger.info("attempting software reconnection, attempt %s", str(i + 1))
+            self.device.disconnect()
+            # add bash script here
+            self.device.connect()
+            confirmed = self.device.read_and_write(self.hb_sm, self.hb_sm)
+            if confirmed:
+                logger.info(
+                    "Connection re-established via software cycling on "
+                    "attempt %s, heartbeat received.",
+                    str(i + 1),
+                )
+                return True
+
+        logger.info("Max connection cycles hit")
+        return False
+
+    def _power_cycle(self) -> bool:
+        """Power cycle all usb ports chip"""
+        if self.device.pca:
+            logger.info("power cycling available")
+            for i in range(self.power_cycles):
+                try:
+                    logger.info("power cycling USB hub, attempt %s", str(i + 1))
+                    # input bash script here
+                    confirmed = self.device.read_and_write(self.hb_sm, self.hb_rm)
+                    if confirmed:
+                        logger.info(
+                            "Connection re-established via power cycling on attempt %s, "
+                            "heartbeat received",
+                            str(i + 1),
+                        )
+                        return True
+                except Exception as e:
+                    logger.error("failed to perfrom power cycle: %s", e)
+            logger.info("max power cycles hit, connection not recovered")
+            return False
+
+        logger.info("power cycling unavailable")
+        return False
+
+    def advanced_connection(self, send_msg: str, receive_msg: str) -> dict[str, bool]:
+        """Handle errors with a heriarchy of recovery methods"""
+        msg_location = {
+            "confirmed": False,
+            "nominal": False,
+            "retries": False,
+            "software_cycle": False,
+            "power_cycle": False,
+        }
+        confirmed = self.send(send_msg, receive_msg)
+        if confirmed:
+            msg_location["nominal"] = True
+            msg_location["confirmed"] = True
+            return msg_location
+        
+        confirmed = self._retries(send_msg, receive_msg)
+        if confirmed:
+            msg_location["retries"] = True
+            msg_location["confirmed"] = True
+            return msg_location
+        
+        reconnected = self._software_cycle()
+        if reconnected:
+            msg_location["software_cycle"] = True
+            result = self.send(send_msg, receive_msg, True)
+            if result:
+                msg_location["confirmed"] = True
+            return msg_location
+        
+        reconnected = self._power_cycle()
+        if reconnected:
+            msg_location["power_cycle"] = True
+            result = self.send(send_msg, receive_msg, True)
+            if result:
+                msg_location["confirmed"] = True
+            return msg_location
+        return msg_location
+
+
+# ---------------------------------------------------------------------------------------
+class Controls:
+    """Perform controls for any registered device"""
+
+    def __init__(self, device_dict: dict[str, AdvancedCommunication]) -> None:
+        self.devices = device_dict
+
+    def heart_beat(self, device_id: str, advanced_connection: bool =False) -> dict[str, bool] | bool:
+        """send heart beat request to device"""
+        logger.info("Sending heartbeat to %s", device_id)
+        confirmation: dict[str, bool] = {}
+
+        correct_device = self.devices[device_id]
+        send_msg = correct_device.hb_sm
+        receive_msg = correct_device.hb_rm
+
+        if advanced_connection: 
+            confirmation = correct_device.advanced_connection(send_msg, receive_msg)
+        else: 
+             confirmation["confirmed"] = correct_device.send(send_msg, receive_msg)
+
+        return confirmation
+    
+    def advanced_send(self, device_name: str,  package: str) -> dict[str, bool] | bool:
+        """Send a message over serial using the advanced communication 
+           heirarchy / built in error recovery""" 
+        correct_device = self.devices[device_name]
+        confirmation = correct_device.advanced_connection(package, package)
+        return confirmation
+    
+    def send(self, device_name: str, package: str) -> bool: 
+         """Send a message over serial with a single send, no built-in error recovery"""
+         correct_device = self.devices[device_name]
+         confirmation = correct_device.send(package, package)
+         return confirmation 
+
+# ---------------------------------------------------------------------------------------

hilsim/core/device_exceptions.py

@@ -0,0 +1,8 @@
+class DeviceError(Exception):
+    """ Base for device-related errors"""
+    def __init__(self, sensor_id: str, message: str) -> None: 
+        self.sensor_id = sensor_id
+        super().__init__(f"[{sensor_id}] {message}")
+
+class DeviceConnectionError(DeviceError):
+    """Raised when a device fails to connect"""