Subsystem SDK Reference
This page is the table-oriented catalog for public subsystem-author SDK
surfaces. For usage guidance, start with
Subsystem SDK API Guide.
Role Classes
| Role |
Python class |
C++ class |
Purpose |
gateway |
librux.wrapper.GatewaySubsystem |
librux::wrapper::GatewaySubsystem |
Hardware or simulator-backed device boundary |
component |
librux.wrapper.ComponentSubsystem |
librux::wrapper::ComponentSubsystem |
Reusable robotics control function |
compound |
librux.wrapper.CompoundSubsystem |
librux::wrapper::CompoundSubsystem |
Robot platform composition and app-facing capability surface |
app |
librux.wrapper.AppSubsystem |
librux::wrapper::AppSubsystem |
Robot task, scenario, SI logic, or product application |
All role classes inherit the common Subsystem behavior.
Construction And Manifest
| Surface |
Python |
C++ |
Purpose |
| Construct subsystem |
GatewaySubsystem(...), ComponentSubsystem(...), CompoundSubsystem(...), AppSubsystem(...) |
role-specific class constructed from SubsystemOptions |
Create one runtime subsystem |
| Name |
name constructor argument |
SubsystemOptions::name |
Runtime subsystem name |
| Manifest path |
manifest_path |
SubsystemOptions::manifest_path |
Load subsystem.yaml declaration |
| Deployment manifest path |
deployment_manifest_path |
use launch bindings or manifest-driven startup |
Optional source-level debug binding data |
| Launch bindings |
environment / launcher managed |
SubsystemOptions::launch_bindings |
Runtime binding hints outside deployment |
| Declared APIs |
manifest-derived declared_apis |
declared_apis() |
APIs declared by public interfaces |
| Declared components |
manifest-derived declared_components |
declared_components() |
component contracts declared by public interfaces |
| Declared capabilities |
manifest-derived declared_capabilities |
available in manifest status |
capability contracts declared by public interfaces |
Code-level declare_api_contract and declare_component are disabled for
ordinary Python subsystem authors. Public declarations should come from
subsystem.yaml.
Binding And Configuration Methods
| Purpose |
Python |
C++ |
| Resolve required interface |
resolve_binding(requirement) |
use launch bindings and control resolution through wrapper/runtime |
| Resolve target subsystem name |
binding_target(requirement) |
use resolved binding target |
| Require app-facing capability |
require_capability(binding, capability=None) |
use resolved binding plus contract-specific wrapper code |
| Read effective runtime bindings |
runtime_bindings() |
reported in heartbeat status |
| Read launch bindings |
launch_bindings property |
SubsystemOptions::launch_bindings |
| Read config data |
config_data |
package/runtime config through app code |
| Read config value |
config_get(...) |
package/runtime config through app code |
| Set config value |
config_set(..., save=False) |
package/runtime config through app code |
| Reload config |
config_reload() |
package/runtime config through app code |
| Save config |
config_save() |
package/runtime config through app code |
Lifecycle Methods
| Purpose |
Python |
C++ |
| Initialize |
initialize() |
initialize() |
| Start |
start() |
start() |
| Pause request |
pause() |
pause() |
| Resume request |
resume() |
resume() |
| Stop request |
stop() |
stop() |
| Fault request |
fault(reason=None) |
fault(reason) |
| Degrade request |
degrade(reason=None) |
degrade(reason) |
| Reset |
reset() |
reset() |
| Terminate |
terminate() |
terminate() |
| Generic transition |
request_lifecycle_transition(...) |
request_lifecycle_transition(...) |
Lifecycle Hooks
| Hook |
Python |
C++ |
Required |
| Initialize implementation |
on_initialize() |
on_initialize() |
yes |
| Start implementation |
on_start() |
on_start() |
yes |
| Terminate implementation |
on_terminate() |
on_terminate() |
yes |
| Reset implementation |
on_reset() |
on_reset() |
yes |
| Pause implementation |
on_pause() |
on_pause() |
no |
| Resume implementation |
on_resume() |
on_resume() |
no |
| Stop implementation |
on_stop() |
on_stop() |
no |
| Fault implementation |
on_fault(reason=None) |
on_fault(reason) |
no |
| Degraded implementation |
on_degraded(reason=None) |
on_degraded(reason) |
no |
| State change callback |
on_state_changed(state) |
on_state_changed(state) |
no |
Event Methods
| Purpose |
Python |
C++ |
| Register publisher |
register_event_publish(topic=..., type=..., size=..., src_attr=..., priority=..., queue_depth=...) |
register_event_publish(EventPublishSpec) |
| Register subscriber |
register_event_subscribe(topic=..., type=..., size=..., dest_attr=..., callback=...) |
register_event_subscribe(EventSubscribeSpec) |
| Publish sample |
publish_event(topic=..., value=..., timestamp=...) |
publish_event(topic, EventPayload, timestamp_ns, priority) |
| Start transport |
start_event_transport() |
start_event_transport() |
| Stop transport |
stop_event_transport() |
stop_event_transport() |
Event endpoints must come from public spec contracts or visibility: internal
manifest endpoint lists. Do not create endpoint names dynamically at runtime.
Control Methods
| Purpose |
Python |
C++ |
| Register control endpoint |
register_control_endpoint(topic, handler, request_type=..., response_type=..., timing_support=...) |
register_control_endpoint(topic, handler, ControlEndpointOptions) |
| List endpoint names |
get_control_info() |
get_control_info() |
| List endpoint metadata |
get_control_contract_info() |
get_control_contract_info() |
| Bind control server |
bind_control(port=None, host="0.0.0.0") |
bind_control(port, host) |
| Start control server |
start_control_server(handler=None) |
start_control_server(...) |
| Stop control server |
stop_control_server() |
stop_control_server() |
| Resolve target |
resolve_control_target(target) |
resolve_control_target(target, host, port) |
| Handshake target |
handshake_control(target, timeout_ms=1000) |
handshake_control(target, timeout_ms) |
| Send without waiting |
send_control(...) |
send_control(...) |
| Receive response |
recv_control(target, type, timeout_ms=0) |
recv_control(target, timeout_ms) |
| Request/response exchange |
transact_control(...) |
transact_control(...) |
| Bound request/response exchange |
transact_bound_control(binding=..., ...) |
resolve binding then transact_control(...) |
In user-facing terms, the topic argument is the Control endpoint key.
Procedure Methods
| Purpose |
Python |
C++ |
| Register Procedure |
register_procedure(name, handler, request_type=..., response_type=..., timing_support=...) |
register_procedure(name, handler, ProcedureOptions) |
| Register typed Procedure |
register_typed_procedure(name, handler, request_type=..., response_type=..., timing_support=...) |
register_typed_procedure(name, handler, request_type, response_type, timing_support) |
| Start Procedure server |
start_procedure_server() |
start_procedure_server() |
| Stop Procedure server |
stop_procedure_server() |
stop_procedure_server() |
| List Procedure names |
get_procedure_info() |
get_procedure_info() |
| List Procedure metadata |
get_procedure_contract_info() |
get_procedure_contract_info() |
| Call Procedure |
call_procedure(target=..., procedure=..., ...) |
call_procedure(target, procedure, params_json, ...) |
| Call bound Procedure |
call_bound_procedure(binding=..., procedure=..., ...) |
resolve binding then call_procedure(...) |
| Call typed Procedure |
call_typed_procedure(target=..., procedure=..., request_type=..., response_type=..., params=...) |
call_typed_procedure(target, procedure, request_type, response_type, params_json, timeout_ms) |
Operation Methods
| Purpose |
Python |
C++ |
| Register Operation |
register_operation(name, handler, request_type=..., feedback_type=..., result_type=..., state_type=..., timing_support=...) |
register_operation(name, handler, OperationOptions) |
| Start Operation server |
start_operation_server() |
start_operation_server() |
| Stop Operation server |
stop_operation_server() |
stop_operation_server() |
| List Operation names |
get_operation_info() |
get_operation_info() |
| List Operation metadata |
get_operation_contract_info() |
get_operation_contract_info() |
| Start Operation |
start_operation(target=..., operation=..., ...) |
start_operation(target, operation, params_json, ...) |
| Start bound Operation |
start_bound_operation(binding=..., operation=..., ...) |
resolve binding then start_operation(...) |
| Cancel Operation |
cancel_operation(target=..., operation_id=...) |
cancel_operation(target, operation_id, timeout_ms) |
| Query Operation |
query_operation(target=..., operation_id=...) |
query_operation(target, operation_id, timeout_ms) |
| Subscribe feedback |
subscribe_operation_feedback(...) |
subscribe_operation_feedback(...) |
| Subscribe result |
subscribe_operation_result(...) |
subscribe_operation_result(...) |
| Subscribe state |
subscribe_operation_state(...) |
subscribe_operation_state(...) |
| Check cancellation |
is_operation_cancel_requested(operation_id) |
ActionContext::is_cancel_requested() |
| Publish feedback |
publish_operation_feedback(operation_id=..., payload=...) |
ActionContext::publish_feedback(...) |
| Publish result |
publish_operation_result(operation_id=..., payload=...) |
ActionContext::publish_result(...) |
| Publish state |
publish_operation_state(operation_id=..., state=..., payload=...) |
ActionContext::publish_state(...) |
| Complete operation |
complete_operation(...) |
ActionContext::succeed(...), fail(...), or canceled(...) |
Timing And Option Types
| Concept |
Python shape |
C++ type |
| Timing request |
dict with execute_after_ns, execute_at_sync_ns, priority, late_policy, max_lateness_ns, correlation_id, request_id |
TimedExchangeTimingOptions |
| Control transaction options |
keyword args on transact_control(...) |
ControlTransactOptions |
| Control endpoint options |
keyword args on register_control_endpoint(...) |
ControlEndpointOptions |
| Procedure call options |
keyword args on call_procedure(...) |
ProcedureCallOptions |
| Procedure endpoint options |
keyword args on register_procedure(...) |
ProcedureOptions |
| Operation start options |
keyword args on start_operation(...) |
OperationStartOptions |
| Operation endpoint options |
keyword args on register_operation(...) |
OperationOptions |
Endpoint timing_support values are none, optional, and required.
Resource Broker Client
Python managed packages can request brokered file descriptors through
librux.core.ResourceBrokerClient.
| Method |
Purpose |
Typical use |
open_udp_socket(...) |
Open an approved UDP socket on a claimed interface |
UDP device protocols |
open_tcp_socket(...) |
Open an approved TCP socket on a claimed interface |
TCP device protocols or managed listeners |
open_frontend_tcp_listener(kind="api" | "ws") |
Open a package frontend loopback listener grant |
package-owned REST or WebSocket backend |
open_can_socket(...) |
Open an approved CAN socket |
CAN or CAN-FD devices |
open_device(path, ...) |
Open an approved device file |
serial, USB, or udev-governed devices |
Resource broker access requires LIBRUX_RESOURCE_LEASE_ID, normally set by
librux launch run or lbx deploy up.
Source Files
| Surface |
Source |
| Python subsystem wrapper |
sdk/python/librux/wrapper/subsystem.py |
| Python resource broker client |
sdk/python/librux/core/resource.py |
| C++ subsystem wrapper |
sdk/cpp/include/librux/wrapper/subsystem.hpp |
| C++ wrapper types |
sdk/cpp/include/librux/wrapper/core_client.hpp |
| C++ runtime client |
sdk/cpp/include/librux/core/client.hpp |