Crate roboplc

Source
Expand description

RoboPLC crates.io page docs.rs page

RoboPLC is an ultimate pack of a framework and tools for creating real-time micro-services, PLCs and industrial-grade robots in Rust.

The crate is designed to let using all its components both separately and together.

RoboPLC is a part of EVA ICS industrial automation platform.

Real-time-safe data synchronization components are re-exported from the RTSC crate which is a part of RoboPLC project and can be used directly, with no requirement to use RoboPLC.

RoboPLC eco-system provides:

§Technical documentation

Available at https://info.bma.ai/en/actual/roboplc/index.html

§Examples

Can be found at https://github.com/roboplc/roboplc/tree/main/examples

§DataBuffer

buf::DataBuffer covers a typical data exchange pattern when data frames are collected (cached) from a single or multiple producers, then taken by a single consumer in bulk and submitted, e.g. into a local database or into an external bus.

  • always has got a fixed capacity

  • thread-safe out-of-the-box

  • frames may be forcibly pushed, overriding the previous ones, like in a ring-buffer.

§Hub

hub::Hub implements a data-hub (in-process pub/sub) model, when multiple clients (usually thread workers) exchange data via a single virtual bus instead of using direct channels.

This brings some additional overhead into data exchange, however makes the architecture significantly clearer, lowers code support costs and brings additional features.

  • classic pub/sub patterns with no data serialization overhead

  • based on policy_channel which allows to mix different kinds of data and apply additional policies if required

  • a fully passive model with no “server” thread.

§pdeque and policy_channel

A policy-based deque rtsc::pdeque::Deque is a component to build policy-based channels.

policy_channel is a channel module, based on the policy-based deque.

Data policies supported:

  • Always a frame is always delivered
  • Latest a frame is always delivered, previous are dropped if no room (acts like a ring-buffer)
  • Optional a frame can be skipped if no room
  • Single a frame must be delivered only once (the latest one)
  • SingleOptional a frame must be delivered only once (the latest one) and is optional

Additionally, components support ordering by data priority and automatically drop expired data if the data type has got an expiration marker method implemented.

policy_channel is a real-time safe channel, mean it may be not so fast as popular channel implementations (it may be even slower than channels provided by std::sync::mpsc). But it is completely safe for real-time applications, mean there are no spin loops, data is always delivered with minimal latency and threads do not block each other.

§Real-time

thread_rt::Builder provides a thread builder component, which extends the standard thread builder with real-time capabilities: scheduler policies and CPU affinity (Linux only).

supervisor::Supervisor provides a lightweight task supervisor to manage launched threads.

§Controller

controller::Controller is the primary component of mixing up all the functionality together.

§I/O

io module provides a set of tools to work with field devices and SCADA buses.

Currently supported:

RoboPLC project provides additional crates, which can be used both with RoboPLC and separately:

  • RTSC - Real-Time Synchronization Components, a set of real-time safe data synchronization components, the core components of RoboPLC

  • atomic-timer - an atomic timer component for typical automation tasks

  • rpdo - RoboPLC Data Objects protocol for data synchronization between processes and devices

  • ehmi - HMI components for egui interfaces.

  • logicline - Logic processing engine

  • metrics-exporter-scope - an oscilloscope-like exporter for metrics eco-system

  • heartbeat-watchdog - heartbeat and watchdog components for mission-critical systems monitoring

  • rvideo - video stream debugging

  • rflow - allows quickly create chat-like diagnostic interfaces for headless programs

§Locking safety

Note: the asynchronous components use parking_lot_rt locking only.

By default, the crate uses parking_lot for locking. For real-time applications, the following features are available:

  • locking-rt - use parking_lot_rt crate which is a spin-free fork of parking_lot.

  • locking-rt-safe - use RTSC priority-inheritance locking, which is not affected by priority inversion (Linux only, recommended Kernel 5.14+).

Note: to switch locking policy, disable the crate default features.

The locking policy can be also selected in CLI when creating a new project:

robo new --locking rt-safe # the default for CLI-created projects is rt-safe

§Using on other platforms

The components thread_rt, supervisor and controller can work on Linux machines only.

Despite of that, “cargo check” should work on Windows and OSX to let developers code RoboPLC-based programs on these platforms. In case if this fails with any crate feature, please report an issue.

§Migration from 0.5.x

  • In case if io::eapi is used, action handlers must now return a serializable value.

  • For proper hmi support, ensure that RuntimeDirectory is configured in roboplc.program service (/lib/systemd/system/roboplc.program.service):

[Service]
# ...
RuntimeDirectory=roboplc
RuntimeDirectoryMode=700

§Migration from 0.4.x

  • Certain thread-rt module components have been moved to rtsc crate. RoboPLC re-exports them, adding compatibility with simulated mode.

  • thread_rt::set_simulated has been moved to set_simulated.

  • thread_rt components CpuGovernor and SystemConfig have been moved to system crate module.

  • openssl-vendored feature has been removed, as EVA ICS EAPI has got now openssl as an optional dependency for certain specific features only.

§Migration from 0.3.x

  • pchannel and pchannel_async have been renamed to policy_channel and policy_channel_async respectively.

  • By default, the crate uses parking_lot for locking. To switch to more safe real-time locking, disable the crate default features and enable either locking-rt or locking-rt-safe. This is important for real-time applications and must be enabled manually.

  • As RTSC components are lock-agnostic, which requires to specify generic locking types, the modules channel, policy_channel, buf and semaphore are now wrappers around RTSC modules with the chosen locking policy.

  • hub_async now requires async feature to be enabled.

§MSRV

Minimum supported mainstream Rust version of RoboPLC is synchronized with the Ferrocene Rust compiler. This allows to create mission-critical software, compliant with ISO 26262 (TCL 3/ASIL D), IEC 61508 (T3) and IEC 62304.

Current MSRV: mainstream 1.83.0, Ferrocene 25.02.0. Certain features may work with older Rust versions.

Re-exports§

pub use logicline;
pub use parking_lot as locking;
pub use metrics;
pub use rvideo;
pub use rflow;

Modules§

buf
Wrapper around rtsc::buf with the chosen locking policy
channel
Wrapper around rtsc::channel with the chosen locking policy
comm
Reliable TCP/Serial communications
controller
Controller and workers
hmi
HMI (Human-Machine Interface) API
hub
In-process data communication pub/sub hub, synchronous edition
hub_async
In-process data communication pub/sub hub, asynchronous edition
io
I/O
policy_channel
Wrapper around rtsc::policy_channel with the chosen locking policy
policy_channel_async
Policy-based async channel
prelude
Prelude module
semaphore
Wrapper around rtsc::semaphore with the chosen locking policy
state
State helper functions
supervisor
Task supervisor to manage real-time threads
system
Linux system tools
thread_rt
Real-time thread functions to work with supervisor::Supervisor and standalone, Linux only
time
Time tools

Macros§

event_matches
A macro which can be used to match an event with enum for Hub subscription condition
init_eapi
Initializes the EAPI module

Structs§

AtomicTimer
Atomic timer

Enums§

DeliveryPolicy
Data delivery policies, used by crate::pdeque::Deque
Error
The crate error type
LevelFilter
An enum representing the available verbosity level filters of the logger.

Traits§

DataChannel
An abstract trait for data channels and hubs
DataDeliveryPolicy
Implements delivery policies for own data types

Functions§

allow_panic_suicide
Allow any thread to kill the process on panic (on by default)
configure_logger
Configures stdout logger with the given filter. If started in production mode, does not logs timestamps
critical
Immediately kills the current process and all its subprocesses with a message to stderr
is_production
Returns true if started in production mode (as a systemd unit)
metrics_exporter
Returns Prometheus metrics exporter builder
metrics_exporter_install
Installs Prometheus metrics exporter together with Scope exporter
prevent_panic_suicide
Prevent other threads to kill the process on panic (the setter still has the ability)
reload_executable
Reload the current executable (performs execvp syscall, Linux only)
serve_rflow
Serves the default rflow server at TCP port 0.0.0.0:4001
serve_rvideo
Serves the default rvideo server at TCP port 0.0.0.0:3001
set_simulated
The function can be used in test environments to disable real-time functions but keep all methods running with no errors
setup_panic
Sets panic handler to immediately kill the process and its childs with SIGKILL. The process is killed when panic happens in ANY thread
suicide
Terminates the current process and all its subprocesses in the specified period of time with SIGKILL command. Useful if a process is unable to shut it down gracefully within a specified period of time.

Type Aliases§

Result
The crate result type

Derive Macros§

DataPolicy
Automatically implements the DataDeliveryPolicy trait for an enum