Module ffi 

C FFI bindings for the PhyTrace SDK.

This module exposes the PhyTrace SDK’s core functionality through a C-compatible ABI, enabling integration with C++ ROS2 nodes and other non-Rust consumers.

Architecture

The FFI layer manages an internal tokio::Runtime per agent handle so that C callers never deal with async. All functions are synchronous from the caller’s perspective.

Memory Model

• Opaque handles (*mut PhyTraceAgent, *mut PhyTraceBuilder, *mut PhyTraceEvent) are heap-allocated and must be freed by the corresponding _destroy function.
• Strings returned by the library (e.g., phytrace_last_error, phytrace_event_to_json) must be freed with phytrace_string_free.
• Null pointers are handled gracefully — functions return PHYTRACE_ERR_NULL_PTR.

Domains Covered

This FFI layer covers the domains required for ROS2 topic integration:

• Identity, Location, Motion, Power, Perception (Lidar + IMU), Safety, Navigation, Actuators (Joints), Operational, Communication, Context

Domains NOT Yet Covered (tracked in issue)

AI, Audio, Compliance, Compute, Coordination, EnvironmentInteraction, HRI, Maintenance, Manipulation, Payload, Simulation, Thermal

Structs

PhyTraceAgentHandle

Opaque handle to a PhyTrace agent with an embedded tokio runtime.

PhyTraceBuilderHandle

Opaque handle to an event builder.

PhyTraceEventHandle

Opaque handle to a built UDM event.

Constants

PHYTRACE_ERR_AGENT

Agent lifecycle error (start, stop, flush).

PHYTRACE_ERR_BUILDER

Event builder error (build validation failed).

PHYTRACE_ERR_CONFIG

Configuration error (invalid YAML, missing fields, validation failure).

PHYTRACE_ERR_INVALID_ENUM

Invalid enum value passed.

PHYTRACE_ERR_INVALID_UTF8

A string argument contained invalid UTF-8.

PHYTRACE_ERR_NULL_PTR

A null pointer was passed where a valid pointer was required.

PHYTRACE_ERR_RUNTIME

Tokio runtime creation failed.

PHYTRACE_ERR_SERIALIZATION

Serialization error (JSON encode/decode).

PHYTRACE_ERR_TRANSPORT

Transport error (send failed).

PHYTRACE_ESTOP_TYPE_AUTOMATIC

EStopType::Automatic

PHYTRACE_ESTOP_TYPE_HARDWARE

EStopType::Hardware

PHYTRACE_ESTOP_TYPE_REMOTE

EStopType::Remote

PHYTRACE_ESTOP_TYPE_SOFTWARE

EStopType::Software

PHYTRACE_EVENT_TYPE_CUSTOM

EventType::Custom

PHYTRACE_EVENT_TYPE_EMERGENCY_STOP

EventType::EmergencyStop

PHYTRACE_EVENT_TYPE_ERROR

EventType::Error

PHYTRACE_EVENT_TYPE_GOAL_REACHED

EventType::GoalReached

PHYTRACE_EVENT_TYPE_MODE_CHANGE

EventType::ModeChange

PHYTRACE_EVENT_TYPE_PATH_BLOCKED

EventType::PathBlocked

PHYTRACE_EVENT_TYPE_REROUTING

EventType::Rerouting

PHYTRACE_EVENT_TYPE_SAFETY_VIOLATION

EventType::SafetyViolation

PHYTRACE_EVENT_TYPE_STATE_TRANSITION

EventType::StateTransition

PHYTRACE_EVENT_TYPE_SYSTEM_SHUTDOWN

EventType::SystemShutdown

PHYTRACE_EVENT_TYPE_SYSTEM_STARTUP

EventType::SystemStartup

PHYTRACE_EVENT_TYPE_TASK_CANCELLED

EventType::TaskCancelled

PHYTRACE_EVENT_TYPE_TASK_COMPLETED

EventType::TaskCompleted

PHYTRACE_EVENT_TYPE_TASK_FAILED

EventType::TaskFailed

PHYTRACE_EVENT_TYPE_TASK_STARTED

EventType::TaskStarted

PHYTRACE_EVENT_TYPE_TELEMETRY_ON_CHANGE

EventType::TelemetryOnChange

PHYTRACE_EVENT_TYPE_TELEMETRY_PERIODIC

EventType::TelemetryPeriodic

PHYTRACE_EVENT_TYPE_TELEMETRY_SNAPSHOT

EventType::TelemetrySnapshot

PHYTRACE_LOCALIZATION_QUALITY_EXCELLENT

LocalizationQuality::Excellent

PHYTRACE_LOCALIZATION_QUALITY_FAIR

LocalizationQuality::Fair

PHYTRACE_LOCALIZATION_QUALITY_GOOD

LocalizationQuality::Good

PHYTRACE_LOCALIZATION_QUALITY_LOST

LocalizationQuality::Lost

PHYTRACE_LOCALIZATION_QUALITY_POOR

LocalizationQuality::Poor

PHYTRACE_OK

Operation succeeded.

PHYTRACE_OPERATIONAL_MODE_AUTONOMOUS

OperationalMode::Autonomous

PHYTRACE_OPERATIONAL_MODE_EMERGENCY

OperationalMode::Emergency

PHYTRACE_OPERATIONAL_MODE_IDLE

OperationalMode::Idle

PHYTRACE_OPERATIONAL_MODE_LEARNING

OperationalMode::Learning

PHYTRACE_OPERATIONAL_MODE_MAINTENANCE

OperationalMode::Maintenance

PHYTRACE_OPERATIONAL_MODE_MANUAL

OperationalMode::Manual

PHYTRACE_OPERATIONAL_MODE_SEMI_AUTONOMOUS

OperationalMode::SemiAutonomous

PHYTRACE_OPERATIONAL_MODE_TELEOPERATED

OperationalMode::Teleoperated

PHYTRACE_OPERATIONAL_STATE_BOOTING

OperationalState::Booting

PHYTRACE_OPERATIONAL_STATE_CHARGING

OperationalState::Charging

PHYTRACE_OPERATIONAL_STATE_EMERGENCY_STOPPED

OperationalState::EmergencyStopped

PHYTRACE_OPERATIONAL_STATE_ERROR

OperationalState::Error

PHYTRACE_OPERATIONAL_STATE_EXECUTING_TASK

OperationalState::ExecutingTask

PHYTRACE_OPERATIONAL_STATE_MANIPULATING

OperationalState::Manipulating

PHYTRACE_OPERATIONAL_STATE_NAVIGATING

OperationalState::Navigating

PHYTRACE_OPERATIONAL_STATE_OFF

OperationalState::Off

PHYTRACE_OPERATIONAL_STATE_PAUSED

OperationalState::Paused

PHYTRACE_OPERATIONAL_STATE_READY

OperationalState::Ready

PHYTRACE_OPERATIONAL_STATE_RECOVERING

OperationalState::Recovering

PHYTRACE_OPERATIONAL_STATE_SHUTTING_DOWN

OperationalState::ShuttingDown

PHYTRACE_PATH_STATE_BLOCKED

PathState::Blocked

PHYTRACE_PATH_STATE_COMPLETED

PathState::Completed

PHYTRACE_PATH_STATE_EXECUTING

PathState::Executing

PHYTRACE_PATH_STATE_FAILED

PathState::Failed

PHYTRACE_PATH_STATE_NONE

PathState::None

PHYTRACE_PATH_STATE_PLANNING

PathState::Planning

PHYTRACE_PATH_STATE_VALID

PathState::Valid

PHYTRACE_SAFETY_STATE_EMERGENCY_STOP

SafetyState::EmergencyStop

PHYTRACE_SAFETY_STATE_NORMAL

SafetyState::Normal

PHYTRACE_SAFETY_STATE_PROTECTIVE_STOP

SafetyState::ProtectiveStop

PHYTRACE_SAFETY_STATE_REDUCED_SPEED

SafetyState::ReducedSpeed

PHYTRACE_SAFETY_STATE_SAFETY_INTERLOCK

SafetyState::SafetyInterlock

PHYTRACE_SAFETY_STATE_WARNING

SafetyState::Warning

PHYTRACE_SOURCE_TYPE_AGV

SourceType::Agv

PHYTRACE_SOURCE_TYPE_AMR

SourceType::Amr

PHYTRACE_SOURCE_TYPE_AUTONOMOUS_FORKLIFT

SourceType::AutonomousForklift

PHYTRACE_SOURCE_TYPE_AUTONOMOUS_VEHICLE

SourceType::AutonomousVehicle

PHYTRACE_SOURCE_TYPE_CLEANING_ROBOT

SourceType::CleaningRobot

PHYTRACE_SOURCE_TYPE_COBOT

SourceType::Cobot

PHYTRACE_SOURCE_TYPE_CUSTOM

SourceType::Custom

PHYTRACE_SOURCE_TYPE_DELIVERY_ROBOT

SourceType::DeliveryRobot

PHYTRACE_SOURCE_TYPE_DRONE

SourceType::Drone

PHYTRACE_SOURCE_TYPE_ELECTRIC_VEHICLE

SourceType::ElectricVehicle

PHYTRACE_SOURCE_TYPE_HUMAN

SourceType::Human

PHYTRACE_SOURCE_TYPE_HUMANOID

SourceType::Humanoid

PHYTRACE_SOURCE_TYPE_INDUSTRIAL_ARM

SourceType::IndustrialArm

PHYTRACE_SOURCE_TYPE_INSPECTION_ROBOT

SourceType::InspectionRobot

PHYTRACE_SOURCE_TYPE_MOBILE_MANIPULATOR

SourceType::MobileManipulator

PHYTRACE_SOURCE_TYPE_QUADRUPED

SourceType::Quadruped

PHYTRACE_SOURCE_TYPE_SECURITY_ROBOT

SourceType::SecurityRobot

PHYTRACE_SOURCE_TYPE_SIMULATION

SourceType::Simulation

Functions

phytrace_agent_create_from_file^⚠

Create a PhyTrace agent from a YAML configuration file path.

phytrace_agent_create_from_yaml^⚠

Create a PhyTrace agent from a YAML configuration string.

phytrace_agent_create_mock^⚠

Create a PhyTrace agent with a mock transport for testing.

phytrace_agent_destroy^⚠

Destroy and free an agent handle.

phytrace_agent_flush^⚠

Flush any buffered events to the transport.

phytrace_agent_is_running^⚠

Check if the agent is currently running.

phytrace_agent_send^⚠

Send a built event through the agent’s transport.

phytrace_agent_start^⚠

Start the agent (connects transport, begins background workers).

phytrace_agent_stop^⚠

Stop the agent gracefully (flushes buffer, disconnects transport).

phytrace_builder_build^⚠

Build the event, consuming the builder.

phytrace_builder_build_unchecked^⚠

Build the event without validation, consuming the builder.

phytrace_builder_destroy^⚠

Destroy a builder without building an event.

phytrace_builder_new^⚠

Create a new event builder from an agent’s configuration.

phytrace_builder_set_actuators_joints^⚠

Set the actuators domain with joint state data.

phytrace_builder_set_communication^⚠

Set the communication domain on the builder.

phytrace_builder_set_context^⚠

Set the context domain on the builder.

phytrace_builder_set_event_type^⚠

Set the event type on the builder.

phytrace_builder_set_extensions_json^⚠

Set arbitrary extensions on the builder as a JSON string.

phytrace_builder_set_identity^⚠

Set the identity domain on the builder.

phytrace_builder_set_location^⚠

Set the location domain on the builder.

phytrace_builder_set_motion^⚠

Set the motion domain on the builder.

phytrace_builder_set_navigation^⚠

Set the navigation domain on the builder.

phytrace_builder_set_operational^⚠

Set the operational domain on the builder.

phytrace_builder_set_perception_imu^⚠

Set the IMU sensor in the perception domain.

phytrace_builder_set_perception_lidar^⚠

Set a lidar sensor in the perception domain.

phytrace_builder_set_power^⚠

Set the power domain on the builder.

phytrace_builder_set_safety^⚠

Set the safety domain on the builder.

phytrace_builder_set_source_type^⚠

Set the source type on the builder.

phytrace_event_destroy^⚠

Destroy a built event without sending it.

phytrace_event_to_json^⚠

Serialize a built event to JSON.

phytrace_last_error

Retrieve the last error message from the FFI layer.

phytrace_sdk_version

Get the PhyTrace SDK version string.

phytrace_string_free^⚠

Free a string allocated by the PhyTrace FFI layer.

phytrace_udm_version

Get the UDM version string supported by this SDK.