DOC 02WORKSPACES

Hardware

The Hardware workspace (Alt+2) is an electronics bench for a marine vehicle. Choose a controller, add sensors, thrusters and power parts from a library of 38, wire them on a canvas while the rules are checked live, generate the firmware project, and run the compiled firmware on an emulated microcontroller whose sensors you drive. This page also covers LEVIATHAN's external interfaces: autopilot software-in-the-loop, ROS 2, replay and remote devices.

Figure 2.1 From a harness to firmware running against simulated sensors.

Table 2.1 Simulation, emulation and real-hardware integration are different things. This table says which each feature is.
Feature	Kind	Needs
Harness wiring, checks, firmware project generation	Design tool	Nothing external; compiling needs PlatformIO
Simulate: RP2040 firmware against simulated sensors	Emulation. Your firmware binary runs on an emulated RP2040; modelled sensors answer it	A compiled .uf2
ArduSub SITL backend	Software-in-the-loop. LEVIATHAN is the physics for an ArduSub SITL instance	An ArduSub SITL build (not bundled)
MAVLink ground-station link	Interface to an autopilot: arm, mode, manual control, telemetry	A MAVLink endpoint, such as SITL
ROS 2 bridge	Interface. Publishes state and sensors, subscribes to thrust commands	A ROS 2 installation
Remote device gateway	Interface. A device on the network publishes its data through LEVIATHAN to viewers in the application	A device or companion computer running a gateway client
Real vehicle hardware	Not driven directly. Real autopilots and companion computers connect through the interfaces above	—

The harness workbench

An empty Hardware workbench: the parts library on the left with Controllers (10) and Sensors (18) groups, each part badged Simulated or Rules only; the controller board drawn on the canvas with its pin labels; Properties on the right showing the controller and an empty firmware section with Generate firmware; the status line reads 0 components, 0 connections, no rule errors found, simulation stopped. — Figure 2.2 A new harness: the library on the left, the controller on the canvas, Properties on the right, and the status line beneath the canvas.

Hardware workbench: the parts library on the left with Controllers and Sensors groups and Simulated or Rules only badges, a Raspberry Pi Pico wired to a Bar30 depth sensor on the canvas, and the Properties panel on the right showing the controller, a 3.3 V power budget of 1.4 mA of 300 mA and a Generate firmware button. The status line reads No rule errors found, 1 unverified, 1 hint. — Figure 2.3 The Hardware workbench: a Bar30 depth sensor wired to a Raspberry Pi Pico over I²C (GP4 and GP5), 3.3 V and ground. The status line under the canvas shows the rule-check result.

The workbench is a single canvas with the parts library on the left and Properties on the right. Its toolbar holds the harness name, Undo and Redo, Save, Check, Simulate and More. A harness is a controller plus parts and the nets between their pins.

Add parts. Click a part in the library, or drag it onto the canvas. Search finds parts by name, and Simulated only limits the list to parts the RP2040 simulator models.
Wire. Click a pin on a part, then a pin on the controller. While a wire is half drawn, pointing at a pin shows what the rules say before you click.
Edit. Delete removes the selection, D duplicates a part, R and Shift+R rotate it, Escape cancels a wire or clears the selection, and Ctrl+Z and Ctrl+Y undo and redo. Shift-click or Shift-drag on the canvas selects several parts.
Properties. With nothing selected, Properties shows the harness: controller, part and bus counts, the power budget per rail, firmware and the power system. Select a part to see and change its settings, its supply and signal levels, and where its power comes from.
More. New harness, open a saved harness, the firmware files for Open in Code, and the earlier Board, Wiring, Devices and Firmware views, kept as legacy views.

Each library row carries an honest badge. Simulated means the RP2040 simulator has a behavioural model for the part, or, for a board, that its firmware runs in the emulator. Rules only means the part is available for wiring and rule checks but is not simulated. The library is grouped as Controllers, Sensors, Propulsion, Power, Communication, Safety and Other, with 38 parts in all. Thumbnails are illustrations, and pin positions on a drawing are not the real connector. More parts can be added as part-description files in ~/.leviathan/devices/.

Table 2.2 Parts in the library.
Kind	Parts
Controllers and computers	Arduino Mega 2560 R3, Arduino Uno R3, ESP32-S3-DevKitC-1, Jetson Orin Nano (companion computer), Navigator Flight Controller, Pixhawk 6C, Raspberry Pi 4 Model B, Raspberry Pi 5, Raspberry Pi Pico, Teensy 4.1
Sensors	ADS1115 ADC, Bar30 depth/pressure, BMP388 barometer, BNO055 and BNO085 IMUs, Celsius temperature, DVL A50, EZO conductivity, H1c hydrophone, ICM-20948 IMU, INA219 power monitor, low-light USB camera, MMC5983MA magnetometer, MPU-6050 IMU, MS5837-02BA depth, NEO-M9N GNSS, Ping altimeter/echosounder, Ping360 scanning sonar, Raspberry Pi Camera Module 3, Underwater GPS Locator U1
Propulsion, power, communication, safety and other	T200 thruster with basic ESC, PCA9685 PWM driver, Newton subsea gripper, Lumen subsea light, 14.8 V 18 Ah Li-ion battery, Fathom-X tether interface, SOS leak sensor, microSD module

Part entries describe interfaces, pins and bus addresses for wiring purposes. Supply and current are as declared in the device library, and each signal level is marked Documented or Unverified. Nothing in a part entry is a bench measurement, an endorsement or performance data.

Rule checks

Checks run as you wire, and Check runs them on demand. The status line under the canvas summarises the result, and Details opens the full list. The checks cover pins (existence, capability, bus instance, double-booking, boot-strapping pins), buses (I²C address collisions and unsettable addresses, SPI chip-select uniqueness, a bus clock faster than its slowest device), electrical limits (supply range per device, current budget per rail, drive limit per pin) and timers (two PWM outputs forced onto one hardware slice).

These are wiring rule checks. They do not simulate the circuit electrically and are not an electrical safety review. Electrically valid is not the same as waterproof: sealing, corrosion and mating are reported separately. Where a part's feed wire is described, its resistance is calculated for copper (IEC 60028 and ASTM B258 gauges). The wire's current rating, sealing and connector suitability do not follow from the gauge alone.

Power

Properties shows a power budget for each rail and, for a vehicle with a battery, the power network: sources, voltage drop along each feed (5 % guideline), wire, connector, fuse and penetrator ratings, and an estimated runtime. It is a DC tree, not a circuit simulator.

Firmware projects

Generate firmware in Properties writes a PlatformIO project for the harness. platformio.ini carries the board, framework and the libraries of every part used, and lev_pins.h carries every pin, bus handle and I²C address. Both are regenerated on each save so they always match the wiring, and they are written read-only, so an edited file is detected. src/main.cpp is yours: it is written once and then left alone. A harness with rule errors cannot produce firmware. The files are written to ~/.leviathan/firmware/<harness>/, and Open in Code opens them as a project in the Code workspace. LEVIATHAN does not compile or flash firmware: you build it in a terminal you control and load the resulting .uf2 into Simulate.

Simulate: firmware against the simulation

Simulate opens the Simulator panel. Load firmware (.uf2) takes the binary your compiler produced and runs it on an emulated RP2040 at 125 MHz, with Run and Reset. The firmware talks to the modelled parts over the buses you wired, and those parts answer from the vehicle's state.

Simulator panel open beside the canvas: Load firmware (.uf2), Run and Reset buttons, vehicle sliders for depth and water temperature with fly it and load a dive links, and one simulated sensor, U1 MS5837-30BA at address 0x76, reading 0.00 m, 1013.3 mbar and 12.0 degrees C. — Figure 2.4 The Simulator panel for the harness in Figure 5.1. The simulated MS5837-30BA already answers from the vehicle state (0.00 m, 1013.3 mbar, 12.0 °C) and waits for a firmware file.

Vehicle source. Sliders set the vehicle state that the simulated parts read, such as depth and water temperature; the sliders shown depend on the parts in the harness. load a dive replays a recorded dive. fly it closes the loop: the firmware's own thruster commands move the simulated vehicle, and the vehicle moves the sensors.
Sensors. Each simulated part is listed with its bus address and the values it is returning.
Emulator readout. Instructions executed, emulated time, clock, pins driven, program counter, boot stage, UART and I²C traffic.
Decoded outputs. Pins the firmware drives light up on the canvas, and PWM on output pins is decoded into actuator commands, such as an ESC pulse width as percent thrust.

Table 2.3 Parts with emulation models in the Simulator.
Bus	Modelled parts	Driven by
I²C	Bar30 (MS5837-30BA), MS5837-02BA, Celsius (TSYS01), BNO055, INA219	Depth, temperature, attitude and rates, bus voltage and current
UART	Ping altimeter (Ping1D protocol), Ping360, DVL A50	Altitude, depth, attitude
GPIO	SOS leak sensor	Leak state

Emulation scope

Parts without a model do not acknowledge on the bus, which firmware reads as absent.
The emulated ADC is not wired, so analog parts such as the H1c hydrophone and battery monitor do not reach firmware.
The RP2040's second core is answered so firmware boots, but code on the second core does not run.
The Simulator emulates the RP2040 only. Other boards in the library are available for wiring and project generation.

External interfaces

ArduSub SITL and MAVLink

LEVIATHAN can act as the physics backend for an ArduPilot SITL instance using ArduPilot's JSON interface. Each frame, SITL sends its servo PWM outputs over UDP, and LEVIATHAN steps the chosen vehicle and replies with the vehicle state. The default vehicle is the BlueROV2 Heavy and the default port is 9002. The Dashboard's SITL / HIL panel starts and stops this backend. It also connects a MAVLink ground-station link to arm and disarm, set the flight mode, send manual control setpoints and read attitude and position telemetry. An ArduSub SITL build is required and is not bundled.

ROS 2

The ROS 2 bridge publishes vehicle state and sensors and subscribes to thrust commands, under the namespace leviathan. The Dashboard's ROS 2 panel shows the topic contract and runs a preview of the messages without ROS. Running the live node needs a ROS 2 installation.

Table 2.4 ROS 2 topic contract.
Topic	Type	Direction
leviathan/odom	nav_msgs/Odometry	Published
leviathan/imu	sensor_msgs/Imu	Published
leviathan/depth	std_msgs/Float64	Published
leviathan/altitude	std_msgs/Float64	Published
leviathan/pressure	sensor_msgs/FluidPressure	Published
leviathan/dvl	geometry_msgs/TwistStamped	Published
leviathan/sonar	sensor_msgs/LaserScan	Published
leviathan/seabed	sensor_msgs/PointCloud2 (latched)	Published
leviathan/cmd_thrust	std_msgs/Float64MultiArray, per thruster in [−1, 1]	Subscribed

Frames are leviathan_ned for the world and base_link_frd for the body. The bridge drives the analytic dynamics, not the canonical World.

Replay

The Replay panel ingests a ROS 2 bag, or an odometry, pose or transform log in JSON or JSONL, and plays the trajectory back in the World.

Remote device gateway

A device, such as a vehicle's companion computer, registers with the simulation service and receives an identifier and a token. It then connects over a WebSocket and publishes messages, and LEVIATHAN relays them to every client watching that device. The device is never exposed directly. Registered devices and whether they are online appear in the Dashboard's data-source selector. LEVIATHAN carries the messages; their content is defined by the device.

Other interfaces

OpenUSD. Scenes and Worlds can be exported as OpenUSD, and OpenUSD scenes can be loaded into the World.
LCM. A channel contract and a publisher for Lightweight Communications and Marshalling exist as a library-level adapter for integrators. The application has no control for it.

Software support versus robot designs

Everything on this page is LEVIATHAN software that works with hardware: design tools, emulation and interfaces. Separately, Azarel develops physical robot designs alongside LEVIATHAN, such as the HC-1 hull crawler and NC-1 niche cleaner modelled in the Hull workspace. Those are concept designs that have not been built or tested. They are not hardware supplied with LEVIATHAN.