### Install Project Dependencies Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/developing.md This command installs all required Python packages listed in the 'requirement.txt' file into the active virtual environment. It ensures that all necessary libraries for the project's core functionality are available. ```bash pip install -r requirement.txt ``` -------------------------------- ### Manually Bring Up CAN Network Interface via CLI Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/hardware.md Provides commands to manually configure and bring up the CAN network interface (`can0`) from the command line. This is an alternative to the `/etc/network/interfaces.d` configuration for quick testing or manual setup. ```bash sudo ip link set can0 type can sudo ip link set can0 up ``` -------------------------------- ### Python Plugin Initialization Method (__init__) Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/plugin.md Initializes an entity instance for the data defined in the configuration. It sets the unique instance ID, calls the superclass initializer, and sets up the logger. This method is the primary entry point for plugin setup. ```python """ Initialize an entity instance for the data defined in data @param: data - data definition defined in config """ def __init__(self, data:dict, mqtt_support: MQTT_Support): self.id: str #= super().__init__(data, mqtt_support) self.Logger = logging.getLogger(__class__.__name__) # do your init here ``` -------------------------------- ### Install Optional Development Dependencies Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/developing.md This command installs additional Python packages specified in 'requirement.dev.txt'. These dependencies are typically used for development, testing, or linting purposes and are not required for the project's runtime operation. ```bash pip install -r requirement.dev.txt ``` -------------------------------- ### Example Floor Plan Configuration in YAML Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/configuration.md This YAML snippet demonstrates how to define various devices within an RV's floor plan. Each entry under the `floorplan` node specifies a device's `name`, `instance` (if applicable), `type`, and a descriptive `instance_name`. This configuration allows the software to interact with specific RV components like lights, thermostats, and water tanks. ```YAML floorplan: - name: DC_LOAD_STATUS instance: 1 type: light_switch instance_name: bedroom light - name: DC_LOAD_STATUS instance: 2 type: light_switch instance_name: living room light - name: DC_LOAD_STATUS instance: 8 type: light_switch instance_name: awning light - name: THERMOSTAT_AMBIENT_STATUS instance: 2 type: temperature instance_name: bedroom temperature - name: TANK_STATUS instance: 0 type: tank_level instance_name: fresh water tank - name: TANK_STATUS instance: 1 type: tank_level instance_name: black waste tank - name: TANK_STATUS instance: 2 type: tank_level instance_name: rear gray waste tank - name: TANK_STATUS instance: 18 type: tank_level instance_name: galley gray waste tank - name: TANK_STATUS instance: 20 type: tank_level instance_name: what tank is this 20 - name: TANK_STATUS instance: 21 type: tank_level instance_name: what tank is this 21 - name: WATER_PUMP_STATUS type: water_pump instance_name: fresh water pump - name: WATERHEATER_STATUS type: waterheater instance: 1 instance_name: main waterheater - name: DC_LOAD_STATUS type: tank_warmer instance: 34 instance_name: waste tank heater - name: DC_LOAD_STATUS type: tank_warmer instance: 35 instance_name: fresh water tank heater ``` -------------------------------- ### Configure CAN Network Interface on Debian Bullseye Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/hardware.md Creates a new network interface configuration file (`can0.conf`) in `/etc/network/interfaces.d` for the CAN bus on Debian Bullseye. This configuration sets the CAN interface to manual, defines the bitrate, and includes pre-up/up/down commands to manage the interface. ```ini auto can0 iface can0 inet manual pre-up /sbin/ip link set can0 type can bitrate 250000 restart-ms 100 up /sbin/ifconfig can0 up down /sbin/ifconfig can0 down ``` -------------------------------- ### Create Python Virtual Environment Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/developing.md This command initializes a new Python virtual environment named 'venv' in the current directory. It isolates project dependencies from the system's global Python installation, ensuring a clean development environment. ```bash python3 -m venv venv ``` -------------------------------- ### Example Logging Configuration in YAML Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/configuration.md This YAML configuration sets up detailed logging for the rvc2mqtt application, adhering to Python's logging dict schema. It defines multiple handlers for console output and file-based logging, including a main application log, a full RVC bus trace log, and a log specifically for unhandled RVC messages. Each file handler is configured with rotation settings and specific log levels. ```YAML # # Logging info # See https://docs.python.org/3/library/logging.config.html#logging-config-dictschema # logger: version: 1 handlers: debug_console_handler: level: INFO class: logging.StreamHandler formatter: brief stream: ext://sys.stdout debug_file_handler: class : logging.handlers.RotatingFileHandler formatter: default maxBytes: 10485760 #10 mb backupCount: 1 level: INFO filename: /config/RVC2MQTT.log mode: w unhandled_file_handler: class : logging.handlers.RotatingFileHandler formatter: trace maxBytes: 10485760 #10 mb backupCount: 1 level: DEBUG filename: /config/UNHANDLED_RVC.log rvc_bus_trace_handler: class : logging.handlers.RotatingFileHandler formatter: trace filename: /config/RVC_FULL_BUS_TRACE.log maxBytes: 10485760 #10 mb backupCount: 3 level: DEBUG loggers: "": # root logger handlers: - debug_console_handler - debug_file_handler level: DEBUG propagate: False "unhandled_rvc": # unhandled messages handlers: - unhandled_file_handler level: DEBUG propagate: False "rvc_bus_trace": # all bus messages handlers: - rvc_bus_trace_handler level: DEBUG propagate: False formatters: brief: format: "% messaggio" default: format: "% asctime % levelname -8s % name -15s % messaggio" datefmt: "%Y-%m-%d %H:%M:%S" trace: format: "% asctime % messaggio" datefmt: "%Y-%m-%d %H:%M:%S" ``` -------------------------------- ### Enable RS485 CAN HAT in Raspberry Pi Boot Configuration Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/hardware.md Modifies the `/boot/config.txt` file to enable the SPI interface and configure the MCP2515 CAN controller overlay. This is crucial for the Waveshare RS485 CAN HAT to function correctly. For HomeAssistantOS, the SD card needs to be accessed from another PC to modify this file. ```ini [all] #dtoverlay=vc4-fkms-v3d dtparam=spi=on dtoverlay=mcp2515-can0,oscillator=12000000,interrupt=25,spimaxfrequency=2000000 ``` -------------------------------- ### Python Plugin Optional Initialization Method (initialize) Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/plugin.md An optional method called once when the plugin object is loaded, after the RVC canbus TX queue and MQTT client are ready. It's a suitable place to request data from the canbus, publish initial info topics, and perform any setup requiring external communication. ```python def initialize(self): """ Optional function Will get called once when the object is loaded. RVC canbus tx queue is available mqtt client is ready. This can be a good place to request data from canbus and publish more info topics """ # publish info to mqtt self.mqtt_support.client.publish(self.status_topic, self.state, retain=True) # request dgn report - this should trigger that light to report # dgn = 1FFBD which is actually BD FF 01 FF 00 00 00 self.Logger.debug("Sending Request for DGN") data = struct.pack("/Scripts/activate.bat ``` ```bash source /bin/activate ``` -------------------------------- ### Activate the virtual CAN bus interface (vcan0) Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/testing.md This command brings the previously created "vcan0" virtual CAN bus interface up, making it active and ready for use. It's a necessary step before interacting with the virtual bus. ```Shell sudo ip link set vcan0 up ``` -------------------------------- ### rvc2mqtt Docker Container Environment Variables Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/docker_deploy.md Configuration parameters for the rvc2mqtt Docker container, set via environment variables. These control network interfaces, file paths, MQTT connection details, and optional TLS settings. Users should mount volumes for floor plan files. ```APIDOC Environment Variables: CAN_INTERFACE_NAME: The network CAN interface name (default: can0) FLOORPLAN_FILE_1: Path to the primary floor plan file (recommend mounting a host volume) FLOORPLAN_FILE_2: Optional path to a second floor plan file (for HA addons UI generated content) LOG_CONFIG_FILE: Optional path to a YAML logging configuration file MQTT_HOST: Host URL for the MQTT server MQTT_PORT: Host port for the MQTT server MQTT_USERNAME: Username for MQTT connection MQTT_PASSWORD: Password for MQTT connection MQTT_CLIENT_ID: MQTT client ID and the bridge node name in MQTT path (default: bridge) MQTT_CA: CA certificate for MQTT server (optional, for TLS) MQTT_CERT: Client certificate for MQTT (optional, for TLS) MQTT_KEY: Client key for MQTT (optional, for TLS) ``` -------------------------------- ### Create a virtual CAN bus (vcan0) on Linux Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/testing.md This command creates a new virtual CAN bus interface named "vcan0" using the `ip link` utility. It's useful for simulating a CAN bus for testing purposes without needing physical hardware. ```Shell sudo ip link add dev vcan0 type vcan ``` -------------------------------- ### Run Unit Tests with Pytest and Coverage Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/developing.md This command executes the project's unit tests using pytest. It generates a detailed HTML test report, calculates code coverage for the 'rvc2mqtt' module, and outputs the coverage report in HTML format, providing insights into test effectiveness. ```bash pytest -v --html=pytest_report.html --self-contained-html --cov=rvc2mqtt --cov-report html:cov_html ``` -------------------------------- ### Build rvc2mqtt Docker Image Locally Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/docker_deploy.md This command builds the rvc2mqtt Docker image from the current directory, tagging it as 'rvc2mqtt'. This is useful for local development and testing purposes, allowing users to create a custom image before deployment. ```bash docker build -t rvc2mqtt . ``` -------------------------------- ### Plugin Class Requirements and Members Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/plugin.md Defines the essential requirements for any plugin subclassing EntityPluginBaseClass, including instantiation by entity_factory and the need for a unique device identifier. It also lists critical instance members that must be set or are available for use within a plugin. ```APIDOC Plugin Requirements: - Must subclass from `EntityPluginBaseClass` or a derivative. - Must define `FACTORY_MATCH_ATTRIBUTES` (dict) for `entity_factory` matching config entries. - Must be able to make a unique and consistent device identifier for MQTT usage. - Do not use relative imports. Plugin Members: - self.id: str Description: Must be set to a unique and consistent value (used for mqtt topic). Must be first thing done in `init`. - self.Logger: Logger Description: Logger for the plugin. Should be initialized during `init` after all super class initialization. - self.status_topic: str Description: Topic string for the device state to publish to. - self.mqtt_support: MQTT_Support Description: mqtt_support object used for pub/sub operations. - self.send_queue: queue Description: Queue used to transmit any RVC can bus messages. Msg must be a dictionary and must supply at least the `dgn` string and 8 byte `data` array. ``` -------------------------------- ### MQTT API for Light Switch Device Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/mqtt.md Defines the MQTT topics and operations for controlling and monitoring a Light Switch device. It includes topics for publishing the light's current status and subscribing to commands to change its state. ```APIDOC Device ID: Topic: /state Operation: publish Description: Status of light. Values: "on", "off" Topic: /cmd Operation: subscribe Description: Command the light. Payload: "on" or "off" ``` -------------------------------- ### Home Assistant MQTT Auto-Discovery Integration Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/mqtt.md Explains how rvc2mqtt integrates with Home Assistant's MQTT auto-discovery feature. It details the required topic path structure and the expected JSON format for the configuration payload. ```APIDOC Discovery Prefix: homeassistant (default) Discovery Topic Path: ////config : Default "homeassistant" : Home Assistant component type (e.g., light, sensor) : Concatenation of rvc2mqtt_client-id_object : Entity ID within the device Config Payload: JSON object Description: Matches Home Assistant configuration requirements (at least all required fields). ``` -------------------------------- ### Python Plugin MQTT Message Processing Callback (process_mqtt_msg) Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/plugin.md Defines the function prototype for handling incoming MQTT messages, used when a device allows control from outside the RV-C network. The mqtt_support object provides a subscription service where this callback can be registered for topics of interest. ```python def process_mqtt_msg(self, topic, payload): ``` -------------------------------- ### MQTT Topic Hierarchy for rvc2mqtt Bridge Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/mqtt.md Describes the general MQTT topic structure used by rvc2mqtt for bridge information and device management. It defines base topics for the bridge's state, metadata, and managed devices. ```APIDOC Base Topic: rvc2mqtt/ Sub-topic: state Description: Reports connected state of bridge to MQTT broker. Values: "online", "offline" Sub-topic: info Description: Contains JSON defined metadata about bridge and rvc2mqtt software. Device Base Topic: rvc2mqtt//d/ Description: Base topic for devices managed by rvc2mqtt. ``` -------------------------------- ### MQTT API for Temperature Sensor Device Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/mqtt.md Describes the MQTT topic for reporting temperature in Celsius from a Temperature Sensor device. This sensor only publishes its state when the temperature value changes, and does not subscribe to any commands. ```APIDOC Device ID: Topic: /state Operation: publish Description: Temperature in Celsius. Update Condition: Only when temperature changes. ``` -------------------------------- ### Python Plugin RVC Message Processing Method (process_rvc_msg) Source: https://github.com/spbrogan/rvc2mqtt/blob/main/docs/plugin.md Processes an incoming RV-C message, determining if it's relevant to the current plugin instance. It's common to use _is_entry_match() from EntityPluginBaseClass for filtering. The method should return True if the message is relevant and exclusively processed, otherwise False. ```python """ Process an incoming rvc message and determine if it is of interest to this instance of this object. It is common to leverage _is_entry_match() from EntityPluginBaseClass If relevant and exclusive - Process the message and return True else - return False """ def process_rvc_msg(self, new_message: dict) -> bool: ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.