knust 0.1.1

Asynchronous KNX/IP library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

//! APCI helpers for KNX application-layer group communication.
//!
// TODO: Only A_GroupValue_* services are implemented. Management APCI
// services (individual address read/write, device descriptor read,
// property/memory read-write, restart, etc.) don't exist — this crate
// cannot act as an ETS-style commissioning/management client, only a
// group-communication one.

use crate::error::{ProtocolError, Result};
use crate::log_protocol;
use crate::logging::LogLevel;

/// KNX group value APCI service.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum GroupValueService {
    /// `A_GroupValue_Read` with no payload.
    Read,
    /// `A_GroupValue_Response` carrying a DPT payload.
    Response(Vec<u8>),
    /// `A_GroupValue_Write` carrying a DPT payload.
    Write(Vec<u8>),
}

impl GroupValueService {
    /// Encode this group service into CEMI APCI/data bytes.
    #[must_use]
    pub fn encode(&self) -> Vec<u8> {
        let result = match self {
            Self::Read => vec![0x00],
            Self::Response(payload) => encode_payload(0x40, payload),
            Self::Write(payload) => encode_payload(0x80, payload),
        };
        log_protocol!(
            LogLevel::Trace,
            "APCI encode: {:?} \u{2192} {} bytes",
            self,
            result.len()
        );
        result
    }

    /// Decode a group service from CEMI TPCI and APCI/data bytes.
    ///
    /// # Errors
    ///
    /// Returns [`ProtocolError::DptError`] if `apci_data` is empty or encodes
    /// a service other than `GroupValueRead`/`Response`/`Write`.
    pub fn decode(tpci: u8, apci_data: &[u8]) -> Result<Self> {
        let first_apci = apci_data
            .first()
            .copied()
            .ok_or_else(|| ProtocolError::DptError {
                dpt_type: "APCI".to_string(),
                details: "Missing APCI data".to_string(),
            })?;
        let service = (u16::from(tpci & 0x03) << 8) | u16::from(first_apci & 0xC0);
        log_protocol!(
            LogLevel::Trace,
            "APCI decode: service=0x{:04X} data_len={}",
            service,
            apci_data.len()
        );

        match service {
            0x0000 => Ok(Self::Read),
            0x0040 => Ok(Self::Response(decode_payload(first_apci, apci_data))),
            0x0080 => Ok(Self::Write(decode_payload(first_apci, apci_data))),
            _ => {
                log_protocol!(
                    LogLevel::Warn,
                    "APCI: unsupported service 0x{:04X}",
                    service
                );
                Err(ProtocolError::DptError {
                    dpt_type: "APCI".to_string(),
                    details: format!("Unsupported group value APCI service: 0x{service:04X}"),
                }
                .into())
            }
        }
    }

    /// Borrow the DPT payload for write/response services.
    #[must_use]
    pub fn payload(&self) -> Option<&[u8]> {
        match self {
            Self::Read => None,
            Self::Response(payload) | Self::Write(payload) => Some(payload),
        }
    }
}

fn encode_payload(service_bits: u8, payload: &[u8]) -> Vec<u8> {
    if payload.len() <= 1 {
        vec![service_bits | (payload.first().copied().unwrap_or(0) & 0x3F)]
    } else {
        let mut apci_data = Vec::with_capacity(payload.len() + 1);
        apci_data.push(service_bits);
        apci_data.extend_from_slice(payload);
        apci_data
    }
}

fn decode_payload(first_apci: u8, apci_data: &[u8]) -> Vec<u8> {
    if apci_data.len() == 1 {
        vec![first_apci & 0x3F]
    } else {
        apci_data[1..].to_vec()
    }
}

#[cfg(test)]
mod tests {
    use super::GroupValueService;

    #[test]
    fn group_value_read_encodes_to_single_zero_apci() {
        assert_eq!(GroupValueService::Read.encode(), vec![0x00]);
    }

    #[test]
    fn group_value_write_binary_round_trip() {
        let encoded = GroupValueService::Write(vec![1]).encode();
        assert_eq!(encoded, vec![0x81]);
        assert_eq!(
            GroupValueService::decode(0x00, &encoded).unwrap(),
            GroupValueService::Write(vec![1])
        );
    }

    #[test]
    fn group_value_response_array_round_trip() {
        let encoded = GroupValueService::Response(vec![0x0c, 0x3f]).encode();
        assert_eq!(encoded, vec![0x40, 0x0c, 0x3f]);
        assert_eq!(
            GroupValueService::decode(0x00, &encoded).unwrap(),
            GroupValueService::Response(vec![0x0c, 0x3f])
        );
    }
}