# std-rs
Pure Rust port of the EPICS [std](https://github.com/epics-modules/std) synApps module — standard records and device support widely used in beamline IOCs at synchrotron and accelerator facilities.
No C dependencies. Just `cargo build`.
**Repository:** <https://github.com/epics-rs/epics-rs>
## Overview
The `std` module is a foundational synApps package providing PID feedback control, rate-limited outputs, formatted timestamps, sequence programs, and dozens of beamline utility databases. It's used as a base layer by virtually every synApps IOC.
std-rs ports the C synApps `std` module to native Rust, including the three core records (`epid`, `throttle`, `timestamp`), four device support implementations, native Rust async replacements for two SNL state machines (`delayDo`, `femto`), and 85 database templates ready to load with `dbLoadRecords`.
## Features
### Records
| **epid** | Extended PID feedback controller (PID + MaxMin modes) | Double |
| **throttle** | Rate-limited output with drive limits and sync input | Double |
| **timestamp** | Wall-clock timestamp with format selection | String |
### epid Record
Extended PID controller with two modes:
- **PID mode** — full Kp/Ki/Kd PID with anti-windup, output deadband, bumpless turn-on, hysteresis-based alarms
- **MaxMin mode** — supervisory tracking that drives the output toward observed setpoint extremes
- Pre-process actions read INP (controlled value) and STPL (setpoint) links before each cycle
- `device_did_compute` flag lets device support replace the built-in PID with hardware-accelerated computation
- Output deadband (ODEL) prevents output oscillation
- Closed-loop / open-loop / supervisory modes via FBON
### throttle Record
Rate-limiting output forwarder:
- Reads input link (INP) and writes to output link (OUT)
- Rate limit RMAX (units/sec)
- Minimum delay RMIN between writes
- SYNC input for forced re-sync to current INP value
- Async delayed reprocess via `ReprocessAfter` action
### timestamp Record
Wall-clock timestamp string with 11 format options:
- ISO 8601, EPICS standard, custom strftime patterns
- Output to OUT link or read directly via VAL
- Periodic update via device support (Time of Day driver)
### Device Support
| **Epid Soft** | epid | Synchronous PID computation each scan cycle |
| **Epid Async Soft** | epid | Trigger-driven async PID with callback completion |
| **Fast Epid** | epid | Interrupt-driven 1 kHz+ PID loop with high-rate readback |
| **Time of Day** | timestamp | Periodic wall-clock update via interval timer |
| **Sec Past Epoch** | longin | Unix epoch seconds counter |
### SNL Programs (Native Rust async)
The synApps `std` module ships with two SNL (State Notation Language) state machines that std-rs reimplements as native Rust async tasks:
- **femto** — Femto FEMTO amplifier gain control state machine. Manages cascaded transimpedance amplifier gain selection with auto-ranging based on signal level.
- **delayDo** — Generic delayed action state machine. Triggers a write after a configurable delay, with abort/restart support.
Both run as `tokio::spawn`'d tasks with `select!` for event/timeout multiplexing — no SNL compiler needed.
### Database Templates (85+ bundled in `db/`)
- **PID** — sync_pid_control, async_pid_control, fast_pid_control with autosave .req files
- **Femto** — DLPCA-200, DHPCA-100, DDPCA-300 amplifier presets
- **Generic state** — countDownTimer, alarmClock, autoShutter, genTweak, genericState (numeric/string/aux variants)
- **Sequence** — 4step, auto_4step (4-position state machines)
- **all_com** — common asyn record templates for serial port count 0/4/8/...88
- **delayDo** — generic delayed action sequencer
### Autosave Request Files
Each database template ships with a paired `.req` file for automatic save/restore via `epics-base-rs` autosave.
## Architecture
```
std-rs/
├── src/
│ ├── lib.rs # public API + std_record_factories()
│ ├── records/
│ │ ├── epid.rs # EpidRecord (PID + MaxMin)
│ │ ├── throttle.rs # ThrottleRecord (rate-limited output)
│ │ └── timestamp.rs # TimestampRecord (formatted wall clock)
│ ├── device_support/
│ │ ├── epid_soft.rs # synchronous PID device support
│ │ ├── epid_soft_callback.rs # async trigger-based variant
│ │ ├── epid_fast.rs # 1 kHz+ interrupt-driven PID
│ │ └── time_of_day.rs # periodic timestamp update
│ └── snl/
│ ├── delay_do.rs # delayDo state machine
│ └── femto.rs # Femto amplifier control
├── db/ # 85 database templates + .req files
└── ui/ # PyDM screens
```
## Usage
```toml
[dependencies]
epics-rs = { version = "0.8", features = ["std"] }
```
### Register All Record Types
```rust
use epics_base_rs::server::ioc_app::IocApplication;
use epics_ca_rs::server::run_ca_ioc;
use std_rs::std_record_factories;
#[epics_base_rs::epics_main]
async fn main() -> epics_base_rs::error::CaResult<()> {
let mut app = IocApplication::new();
// Register epid, throttle, timestamp record types
for (name, factory) in std_record_factories() {
app = app.register_record_type(name, factory);
}
app.db_file("db/sync_pid_control.db", ¯os)?
.run(run_ca_ioc)
.await
}
```
### Load a PID Loop
```bash
# Set up a PID feedback loop
caput PID:KP 0.5
caput PID:KI 0.1
caput PID:KD 0.01
caput PID:VAL 25.0 # setpoint
caput PID:FBON 1 # enable feedback
# Watch the controlled variable converge
camonitor PID:CVAL PID:OVAL
```
## Testing
```bash
cargo test -p std-rs
```
Test coverage: PID computation correctness, anti-windup, output deadband, MaxMin tracking, throttle rate limiting, sync input behavior, timestamp format generation, delayDo state transitions, femto auto-ranging.
## Dependencies
- epics-base-rs — Record trait, DeviceSupport, ProcessAction
- asyn-rs — port driver (used by Femto cascaded amplifier)
- chrono — timestamp formatting
- epics-macros-rs — `#[derive(EpicsRecord)]`
## Requirements
- Rust 1.85+ (edition 2024)
## License
[EPICS Open License](../../LICENSE)
## See Also
- [EPICS std module](https://github.com/epics-modules/std) — original C synApps source
- [synApps documentation](https://epics-modules.github.io/) — beamline IOC reference