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

use super::dpt_type::DptType;
use super::payload::DptPayload;
use super::unit::Unit;
use super::view::DptView;
use crate::error::Result;
use crate::log_protocol;
use crate::logging::LogLevel;
use crate::protocol::address::{GroupAddress, IndividualAddress};
use crate::protocol::telegram::{Telegram, TelegramType};

/// A fully decoded telegram with type-safe access to all fields.
pub struct DecodedTelegram<'a> {
    pub source: IndividualAddress,
    pub destination: GroupAddress,
    pub telegram_type: TelegramType,
    pub dpt: DptType,
    pub view: DptView<'a>,
    pub gateway_id: Option<u16>,
    pub group_name: Option<&'a str>,
}

impl<'a> DecodedTelegram<'a> {
    #[must_use]
    pub fn raw(&self) -> &'a [u8] {
        self.view.raw()
    }
    #[must_use]
    pub fn numeric(&self) -> Option<f64> {
        self.view.as_f64()
    }
    #[must_use]
    pub fn unit(&self) -> Option<Unit> {
        self.dpt.unit()
    }
    #[must_use]
    pub fn formatted(&self) -> String {
        let payload = DptPayload::from(self.view);
        payload.formatted(self.dpt.unit())
    }
    #[must_use]
    pub fn to_owned_payload(&self) -> DptPayload {
        DptPayload::from(self.view)
    }
    #[must_use]
    pub fn is_write(&self) -> bool {
        self.telegram_type == TelegramType::GroupValueWrite
    }
    #[must_use]
    pub fn is_response(&self) -> bool {
        self.telegram_type == TelegramType::GroupValueResponse
    }
    #[must_use]
    pub fn is_read(&self) -> bool {
        self.telegram_type == TelegramType::GroupValueRead
    }
}

/// Decode a telegram given its DPT type.
///
/// # Errors
///
/// Returns [`ProtocolError::DptError`](crate::error::ProtocolError::DptError)
/// if `telegram.destination` is not a group address, or if the payload
/// doesn't match `dpt`'s expected encoding.
pub fn decode_telegram<'a>(
    telegram: &'a Telegram,
    dpt: DptType,
    group_name: Option<&'a str>,
) -> Result<DecodedTelegram<'a>> {
    let crate::protocol::address::Address::Group(destination) = telegram.destination else {
        return Err(crate::error::ProtocolError::DptError {
            dpt_type: dpt.number_str(),
            details: "telegram destination is not a group address".to_string(),
        }
        .into());
    };

    let view = match dpt.decode_ref(&telegram.payload) {
        Ok(v) => v,
        Err(e) => {
            log_protocol!(
                LogLevel::Warn,
                "DPT {} decode failed for telegram {} \u{2192} {}: {}",
                dpt.number_str(),
                telegram.source,
                destination,
                e,
            );
            return Err(e);
        }
    };

    log_protocol!(
        LogLevel::Debug,
        "\u{2190} {} {} \u{2192} {} '{}' [DPT {}] = {}",
        telegram.telegram_type,
        telegram.source,
        destination,
        group_name.unwrap_or("?"),
        dpt.number_str(),
        view.formatted(dpt),
    );

    Ok(DecodedTelegram {
        source: telegram.source,
        destination,
        telegram_type: telegram.telegram_type,
        dpt,
        view,
        gateway_id: telegram.gateway_id,
        group_name,
    })
}