mod codec;
mod configuration;
mod control;
mod diagnostics;
mod identity;
mod information;
mod process;
mod text;
use alloc::vec::Vec;
use thiserror::Error;
use crate::{
catalog::{OperationSafety, command_descriptor},
wire::{Address, Frame, FrameKind, PhysicalLayer, WireError},
};
pub use codec::{PayloadReader, PayloadWriter};
pub use configuration::{
LoopConfiguration, PollingAddress, ReadLoopConfiguration, WriteLegacyPollingAddress,
WritePollingAddress,
};
pub use control::{
ActionCommand, AnalogTrim, EepromControl, FixedCurrent, RangeValues, SetDamping, SetRange,
WritePrimaryUnit, WriteTransferFunction,
};
pub use diagnostics::{AdditionalStatus, ReadAdditionalStatus};
pub use identity::ReadIdentity;
pub use identity::{DeviceIdentity, ReadDeviceIdentity};
pub use information::{
ReadFinalAssemblyNumber, ReadOutputInformation, ReadTransducerInformation,
WriteFinalAssemblyNumber,
};
pub use process::{
DeviceVariable, DeviceVariables, DynamicValues, LoopSignal, MeasuredValue, PrimaryValue,
ReadDeviceVariables, ReadDynamicValues, ReadLoopSignal, ReadPrimaryValue,
ReadSelectedVariables, ReadVariableClassifications, SelectedVariable, VariableClassifications,
};
pub use text::{
DeviceDate, ReadLongTag, ReadMessage, ReadTagDescriptorDate, TagDescriptorDate, WriteLongTag,
WriteMessage, WriteTagDescriptorDate, pack_text, unpack_text,
};
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct CommandCode(u16);
impl CommandCode {
pub const fn new(value: u16) -> Self {
Self(value)
}
pub const fn get(self) -> u16 {
self.0
}
pub const fn is_expanded(self) -> bool {
self.0 > u8::MAX as u16
}
}
impl From<u8> for CommandCode {
fn from(value: u8) -> Self {
Self(u16::from(value))
}
}
impl From<u16> for CommandCode {
fn from(value: u16) -> Self {
Self(value)
}
}
#[derive(Debug, Clone, PartialEq, Error)]
pub enum OperationError {
#[error("expected command {expected}, received command {actual}")]
CommandMismatch {
expected: u16,
actual: u16,
},
#[error("device returned response code {code} and status 0x{status:02x}")]
DeviceStatus {
code: u8,
status: u8,
},
#[error("device reported communication status 0x{summary:02x} and status 0x{status:02x}")]
CommunicationStatus {
summary: u8,
status: u8,
},
#[error("field {field} is truncated at offset {offset}")]
Truncated {
field: &'static str,
offset: usize,
},
#[error("{0} unexpected bytes remain after decoding")]
TrailingBytes(usize),
#[error("field {0} is outside the allowed range")]
InvalidValue(&'static str),
#[error("command {command} does not accept a {actual}-byte request")]
RequestLength {
command: u16,
actual: usize,
},
#[error(transparent)]
Wire(#[from] WireError),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Request {
pub address: Address,
pub command: CommandCode,
pub data: Vec<u8>,
pub preambles: u8,
pub frame_expansion: Vec<u8>,
pub physical_layer: PhysicalLayer,
pub retry_safety: Option<OperationSafety>,
}
impl Request {
pub fn new(address: Address, command: impl Into<CommandCode>, data: Vec<u8>) -> Self {
Self {
address,
command: command.into(),
data,
preambles: 5,
frame_expansion: Vec::new(),
physical_layer: PhysicalLayer::Fsk,
retry_safety: None,
}
}
pub fn try_new(
address: Address,
command: impl Into<CommandCode>,
data: impl Into<Vec<u8>>,
) -> Result<Self, OperationError> {
let request = Self::new(address, command, data.into());
request.validate()?;
Ok(request)
}
pub const fn with_preambles(mut self, preambles: u8) -> Self {
self.preambles = preambles;
self
}
pub const fn with_physical_layer(mut self, physical_layer: PhysicalLayer) -> Self {
self.physical_layer = physical_layer;
self
}
pub fn with_frame_expansion(
mut self,
expansion: impl Into<Vec<u8>>,
) -> Result<Self, OperationError> {
let expansion = expansion.into();
if expansion.len() > 3 {
return Err(OperationError::InvalidValue("frame expansion length"));
}
self.frame_expansion = expansion;
Ok(self)
}
pub const fn with_retry_safety(mut self, safety: OperationSafety) -> Self {
self.retry_safety = Some(safety);
self
}
pub fn validate(&self) -> Result<(), OperationError> {
let service_bytes = usize::from(self.command.is_expanded()) * 2;
let payload_len = self.data.len().saturating_add(service_bytes);
if payload_len > usize::from(u8::MAX) {
return Err(OperationError::Wire(WireError::PayloadLength(payload_len)));
}
if self.frame_expansion.len() > 3 {
return Err(OperationError::Wire(WireError::ExpansionLength(
self.frame_expansion.len(),
)));
}
Ok(())
}
pub fn to_frame(&self) -> Result<Frame, OperationError> {
self.validate()?;
let (wire_command, payload) = if self.command.is_expanded() {
let mut payload = Vec::with_capacity(self.data.len() + 2);
payload.extend_from_slice(&self.command.get().to_be_bytes());
payload.extend_from_slice(&self.data);
(31, payload)
} else {
(
u8::try_from(self.command.get())
.map_err(|_| OperationError::InvalidValue("standard command number"))?,
self.data.clone(),
)
};
let frame = Frame {
preambles: self.preambles,
kind: FrameKind::Request,
physical_layer: self.physical_layer,
address: self.address,
expansion: self.frame_expansion.clone(),
wire_command,
payload,
repair: None,
};
frame.delimiter()?;
Ok(frame)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeviceReply {
pub address: Address,
pub command: CommandCode,
pub response_code: u8,
pub device_status: u8,
pub data: Vec<u8>,
pub burst: bool,
pub physical_layer: PhysicalLayer,
pub response_preambles: u8,
pub frame_expansion: Vec<u8>,
}
impl DeviceReply {
pub fn from_frame(frame: Frame) -> Result<Self, OperationError> {
let Frame {
preambles,
kind,
physical_layer,
address,
expansion,
wire_command,
payload,
..
} = frame;
if !matches!(kind, FrameKind::Response | FrameKind::Burst) {
return Err(OperationError::InvalidValue("response frame type"));
}
if payload.len() < 2 {
return Err(OperationError::Truncated {
field: "response code and status",
offset: payload.len(),
});
}
let response_code = payload[0];
let device_status = payload[1];
let (command, data_start) = if wire_command == 31 {
if payload.len() < 4 {
return Err(OperationError::Truncated {
field: "expanded command number",
offset: payload.len(),
});
}
(
CommandCode::new(u16::from_be_bytes([payload[2], payload[3]])),
4,
)
} else {
(CommandCode::from(wire_command), 2)
};
Ok(Self {
address,
command,
response_code,
device_status,
data: payload[data_start..].to_vec(),
burst: kind == FrameKind::Burst,
physical_layer,
response_preambles: preambles,
frame_expansion: expansion,
})
}
pub fn require_success(&self, expected: CommandCode) -> Result<(), OperationError> {
self.require_command(expected)?;
if self.response_code & 0x80 != 0 {
return Err(OperationError::CommunicationStatus {
summary: self.response_code,
status: self.device_status,
});
}
if self.response_code != 0 {
return Err(OperationError::DeviceStatus {
code: self.response_code,
status: self.device_status,
});
}
Ok(())
}
pub fn require_command(&self, expected: CommandCode) -> Result<(), OperationError> {
if self.command != expected {
return Err(OperationError::CommandMismatch {
expected: expected.get(),
actual: self.command.get(),
});
}
Ok(())
}
pub const fn has_communication_error(&self) -> bool {
self.response_code & 0x80 != 0
}
pub const fn is_success(&self) -> bool {
self.response_code == 0
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct CommandOutcome<T> {
pub value: T,
pub response_code: u8,
pub device_status: u8,
}
impl<T> CommandOutcome<T> {
pub const fn is_warning(&self) -> bool {
self.response_code != 0
}
}
pub trait Operation {
type Output;
fn command(&self) -> CommandCode;
fn retry_safety(&self) -> OperationSafety {
command_descriptor(self.command()).map_or(OperationSafety::Action, |entry| entry.safety)
}
fn encode_request(&self, writer: &mut PayloadWriter) -> Result<(), OperationError>;
fn decode_reply(&self, reply: &DeviceReply) -> Result<Self::Output, OperationError>;
fn decode_reply_accepting(
&self,
reply: &DeviceReply,
accepted_warnings: &[u8],
) -> Result<CommandOutcome<Self::Output>, OperationError> {
reply.require_command(self.command())?;
if reply.has_communication_error() {
return Err(OperationError::CommunicationStatus {
summary: reply.response_code,
status: reply.device_status,
});
}
if reply.response_code != 0 && !accepted_warnings.contains(&reply.response_code) {
return Err(OperationError::DeviceStatus {
code: reply.response_code,
status: reply.device_status,
});
}
let mut accepted = reply.clone();
accepted.response_code = 0;
Ok(CommandOutcome {
value: self.decode_reply(&accepted)?,
response_code: reply.response_code,
device_status: reply.device_status,
})
}
fn request(&self, address: Address) -> Result<Request, OperationError> {
let mut writer = PayloadWriter::new();
self.encode_request(&mut writer)?;
Ok(Request::new(address, self.command(), writer.finish())
.with_retry_safety(self.retry_safety()))
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RawOperation {
command: CommandCode,
data: Vec<u8>,
retry_safety: OperationSafety,
}
impl RawOperation {
pub fn new(command: impl Into<CommandCode>, data: impl Into<Vec<u8>>) -> Self {
Self {
command: command.into(),
data: data.into(),
retry_safety: OperationSafety::Action,
}
}
pub fn read(command: impl Into<CommandCode>, data: impl Into<Vec<u8>>) -> Self {
Self::new(command, data).with_retry_safety(OperationSafety::ReadOnly)
}
pub fn idempotent_write(command: impl Into<CommandCode>, data: impl Into<Vec<u8>>) -> Self {
Self::new(command, data).with_retry_safety(OperationSafety::IdempotentWrite)
}
pub fn action(command: impl Into<CommandCode>, data: impl Into<Vec<u8>>) -> Self {
Self::new(command, data)
}
pub const fn with_retry_safety(mut self, safety: OperationSafety) -> Self {
self.retry_safety = safety;
self
}
}
impl Operation for RawOperation {
type Output = DeviceReply;
fn command(&self) -> CommandCode {
self.command
}
fn retry_safety(&self) -> OperationSafety {
self.retry_safety
}
fn encode_request(&self, writer: &mut PayloadWriter) -> Result<(), OperationError> {
writer.bytes(&self.data);
Ok(())
}
fn request(&self, address: Address) -> Result<Request, OperationError> {
let maximum = if self.command.is_expanded() { 253 } else { 255 };
if self.data.len() > maximum {
return Err(OperationError::RequestLength {
command: self.command.get(),
actual: self.data.len(),
});
}
Ok(Request::new(address, self.command, self.data.clone())
.with_retry_safety(self.retry_safety))
}
fn decode_reply(&self, reply: &DeviceReply) -> Result<Self::Output, OperationError> {
if reply.command != self.command {
return Err(OperationError::CommandMismatch {
expected: self.command.get(),
actual: reply.command.get(),
});
}
Ok(reply.clone())
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CheckedOperation {
command: CommandCode,
data: Vec<u8>,
retry_safety: OperationSafety,
}
impl CheckedOperation {
pub fn new(
command: impl Into<CommandCode>,
data: impl Into<Vec<u8>>,
) -> Result<Self, OperationError> {
let command = command.into();
let data = data.into();
let fits_frame = if command.is_expanded() {
data.len() <= usize::from(u8::MAX) - 2
} else {
u8::try_from(data.len()).is_ok()
};
if !fits_frame || !crate::catalog::request_constraint(command).allows(data.len()) {
return Err(OperationError::RequestLength {
command: command.get(),
actual: data.len(),
});
}
let retry_safety = command_descriptor(command)
.map_or(OperationSafety::Action, |descriptor| descriptor.safety);
Ok(Self {
command,
data,
retry_safety,
})
}
pub const fn with_retry_safety(mut self, safety: OperationSafety) -> Self {
self.retry_safety = safety;
self
}
}
impl Operation for CheckedOperation {
type Output = DeviceReply;
fn command(&self) -> CommandCode {
self.command
}
fn retry_safety(&self) -> OperationSafety {
self.retry_safety
}
fn encode_request(&self, writer: &mut PayloadWriter) -> Result<(), OperationError> {
writer.bytes(&self.data);
Ok(())
}
fn decode_reply(&self, reply: &DeviceReply) -> Result<Self::Output, OperationError> {
if reply.command != self.command {
return Err(OperationError::CommandMismatch {
expected: self.command.get(),
actual: reply.command.get(),
});
}
Ok(reply.clone())
}
}