bacnet_encoding/constructed/
fault_parameter.rs

1//! `BACnetFaultParameter` full ASN.1 framing.
2//!
3//! `BACnetFaultParameter` (ASHRAE 135-2020 Clause 21) selects one fault
4//! algorithm by context tag and carries its settings; [`FaultParameters`]
5//! models every alternative. `none` is a primitive NULL. Every other
6//! alternative is a constructed value holding context-tagged members, all
7//! required:
8//!
9//! | Tag | Alternative | Member tag | Member | Type |
10//! |---|---|---|---|---|
11//! | `[0]` | `none` | | | NULL, no members |
12//! | `[1]` | `fault-characterstring` | `[0]` | `list-of-fault-values` | list of CharacterString |
13//! | `[2]` | `fault-extended` | `[0]` | `vendor-id` | Unsigned16 |
14//! | | | `[1]` | `extended-fault-type` | Unsigned |
15//! | | | `[2]` | `parameters` | list of extended values, see below |
16//! | `[3]` | `fault-life-safety` | `[0]` | `list-of-fault-values` | list of life-safety states |
17//! | | | `[1]` | `mode-property-reference` | `BACnetDeviceObjectPropertyReference` |
18//! | `[4]` | `fault-state` | `[0]` | `list-of-fault-values` | list of `BACnetPropertyStates` |
19//! | `[5]` | `fault-status-flags` | `[0]` | `status-flags-reference` | device property reference |
20//! | `[6]` | `fault-out-of-range` | `[0]` | `min-normal-value` | numeric choice, see below |
21//! | | | `[1]` | `max-normal-value` | the same four-way choice |
22//! | `[7]` | `fault-listed` | `[0]` | `fault-list-reference` | device property reference |
23//!
24//! Each "device property reference" is a `BACnetDeviceObjectPropertyReference`,
25//! and the life-safety list holds `BACnetLifeSafetyState` values. Each extended
26//! `parameters` entry is an application-tagged primitive or a `[0]`-framed
27//! `BACnetDeviceObjectPropertyReference`.
28//!
29//! The min/max inner CHOICE alternatives are untagged — discovered by their
30//! APPLICATION tag (REAL=4, Unsigned=2, Double=5, INTEGER=3). The Rust type
31//! stores `f64`, so encode always selects the `Double` alternative; decode
32//! accepts all four.
33
34#[cfg(not(feature = "std"))]
35use alloc::{string::ToString, vec::Vec};
36
37use bacnet_types::constructed::FaultParameters;
38use bacnet_types::enums::LifeSafetyState;
39use bacnet_types::error::Error;
40use bytes::BytesMut;
41
42use crate::primitives;
43use crate::tags::{self, TagClass};
44
45use super::tagged::{
46    contents, decode_app_character_string, decode_app_enumerated, decode_ctx_constructed,
47    decode_ctx_unsigned, expect_closing, expect_opening, next_is_closing,
48};
49use super::{
50    decode_dopr_body, decode_property_state, encode_dopr_body, encode_property_state,
51    validate_extended_parameters, MAX_FRAMED_ITEMS,
52};
53
54/// Encode a [`FaultParameters`] as its full CHOICE framing.
55pub fn encode_fault_parameters(buf: &mut BytesMut, value: &FaultParameters) -> Result<(), Error> {
56    let mut encoded = BytesMut::new();
57    encode_fault_parameters_into(&mut encoded, value)?;
58    super::validate_tlv_sequence(&encoded, "FaultParameters")
59        .map_err(|error| Error::Encoding(error.to_string()))?;
60    buf.extend_from_slice(&encoded);
61    Ok(())
62}
63
64fn encode_fault_parameters_into(buf: &mut BytesMut, value: &FaultParameters) -> Result<(), Error> {
65    use FaultParameters as F;
66    match value {
67        F::FaultNone => {
68            // none [0] NULL — primitive context tag, no contents.
69            tags::encode_tag(buf, 0, TagClass::Context, 0);
70        }
71        F::FaultCharacterString { fault_values } => {
72            tags::encode_opening_tag(buf, 1);
73            tags::encode_opening_tag(buf, 0);
74            for s in fault_values {
75                primitives::encode_app_character_string(buf, s)?;
76            }
77            tags::encode_closing_tag(buf, 0);
78            tags::encode_closing_tag(buf, 1);
79        }
80        F::FaultExtended {
81            vendor_id,
82            extended_fault_type,
83            parameters,
84        } => {
85            validate_extended_parameters(parameters, "fault-extended")
86                .map_err(|error| Error::Encoding(error.to_string()))?;
87            tags::encode_opening_tag(buf, 2);
88            primitives::encode_ctx_unsigned(buf, 0, *vendor_id as u64);
89            primitives::encode_ctx_unsigned(buf, 1, *extended_fault_type as u64);
90            tags::encode_opening_tag(buf, 2);
91            buf.extend_from_slice(parameters);
92            tags::encode_closing_tag(buf, 2);
93            tags::encode_closing_tag(buf, 2);
94        }
95        F::FaultLifeSafety {
96            fault_values,
97            mode_property_reference,
98        } => {
99            tags::encode_opening_tag(buf, 3);
100            tags::encode_opening_tag(buf, 0);
101            for v in fault_values {
102                primitives::encode_app_enumerated(buf, v.to_raw());
103            }
104            tags::encode_closing_tag(buf, 0);
105            // mode-property-reference [1] BACnetDeviceObjectPropertyReference
106            tags::encode_opening_tag(buf, 1);
107            encode_dopr_body(buf, mode_property_reference);
108            tags::encode_closing_tag(buf, 1);
109            tags::encode_closing_tag(buf, 3);
110        }
111        F::FaultState { fault_values } => {
112            let mut encoded_states = BytesMut::new();
113            for state in fault_values {
114                encode_property_state(&mut encoded_states, state)?;
115            }
116            tags::encode_opening_tag(buf, 4);
117            tags::encode_opening_tag(buf, 0);
118            buf.extend_from_slice(&encoded_states);
119            tags::encode_closing_tag(buf, 0);
120            tags::encode_closing_tag(buf, 4);
121        }
122        F::FaultStatusFlags { reference } => {
123            tags::encode_opening_tag(buf, 5);
124            tags::encode_opening_tag(buf, 0);
125            encode_dopr_body(buf, reference);
126            tags::encode_closing_tag(buf, 0);
127            tags::encode_closing_tag(buf, 5);
128        }
129        F::FaultOutOfRange {
130            min_normal,
131            max_normal,
132        } => {
133            tags::encode_opening_tag(buf, 6);
134            // min/max-normal-value [n] CHOICE — explicitly tagged around the
135            // application-tagged alternative; the model stores f64, so the
136            // `double` alternative encodes it losslessly.
137            tags::encode_opening_tag(buf, 0);
138            primitives::encode_app_double(buf, *min_normal);
139            tags::encode_closing_tag(buf, 0);
140            tags::encode_opening_tag(buf, 1);
141            primitives::encode_app_double(buf, *max_normal);
142            tags::encode_closing_tag(buf, 1);
143            tags::encode_closing_tag(buf, 6);
144        }
145        F::FaultListed { reference } => {
146            tags::encode_opening_tag(buf, 7);
147            tags::encode_opening_tag(buf, 0);
148            encode_dopr_body(buf, reference);
149            tags::encode_closing_tag(buf, 0);
150            tags::encode_closing_tag(buf, 7);
151        }
152    }
153    Ok(())
154}
155
156/// Decode one application-tagged REAL/Unsigned/Double/INTEGER as f64 — the
157/// `fault-out-of-range` min/max inner CHOICE alternatives.
158fn decode_fault_normal_value(data: &[u8], offset: usize) -> Result<(f64, usize), Error> {
159    let (t, pos) = tags::decode_tag(data, offset)?;
160    if t.class != TagClass::Application || t.is_opening || t.is_closing {
161        return Err(Error::decoding(
162            offset,
163            "fault-out-of-range: min/max-normal-value must be application-tagged",
164        ));
165    }
166    let what = "fault-out-of-range min/max-normal-value";
167    if t.number == tags::app_tag::BOOLEAN {
168        return Err(Error::decoding(
169            offset,
170            format!("{what}: BOOLEAN is not a valid alternative"),
171        ));
172    }
173    let (content, end) = contents(data, pos, t.length)?;
174    let value = match t.number {
175        tags::app_tag::REAL => primitives::decode_real(content)? as f64,
176        tags::app_tag::UNSIGNED => primitives::decode_unsigned(content)? as f64,
177        tags::app_tag::DOUBLE => primitives::decode_double(content)?,
178        tags::app_tag::SIGNED => primitives::decode_signed(content)? as f64,
179        other => {
180            return Err(Error::decoding(
181                offset,
182                format!("{what}: unexpected application tag {other}"),
183            ))
184        }
185    };
186    Ok((value, end))
187}
188
189/// Decode one framed [`FaultParameters`] CHOICE alternative at `offset`.
190///
191/// Returns the value and the offset past its encoding.
192pub fn decode_fault_parameters(
193    data: &[u8],
194    offset: usize,
195) -> Result<(FaultParameters, usize), Error> {
196    use FaultParameters as F;
197    let (tag, pos) = tags::decode_tag(data, offset)?;
198    let what = "BACnetFaultParameter";
199
200    // none [0] NULL — primitive context tag, no contents.
201    if tag.is_context(0) {
202        if tag.length != 0 {
203            return Err(Error::decoding(
204                offset,
205                "BACnetFaultParameter: none [0] NULL must have no contents",
206            ));
207        }
208        return Ok((F::FaultNone, pos));
209    }
210    if !tag.is_opening {
211        return Err(Error::decoding(
212            offset,
213            "BACnetFaultParameter: expected an opening context tag or [0] NULL",
214        ));
215    }
216
217    let value = match tag.number {
218        1 => {
219            let mut pos = expect_opening(data, pos, 0, what)?;
220            let mut fault_values = Vec::new();
221            while !next_is_closing(data, pos, 0)? {
222                if fault_values.len() >= MAX_FRAMED_ITEMS {
223                    return Err(Error::overflow(
224                        pos,
225                        "fault-characterstring: list-of-fault-values exceeds limit",
226                    ));
227                }
228                let (s, p) = decode_app_character_string(data, pos, what)?;
229                fault_values.push(s);
230                pos = p;
231            }
232            pos = expect_closing(data, pos, 0, what)?;
233            pos = expect_closing(data, pos, 1, what)?;
234            (F::FaultCharacterString { fault_values }, pos)
235        }
236        2 => {
237            let what = "BACnetFaultParameter fault-extended";
238            let (vendor_id, pos) = decode_ctx_unsigned::<u16>(data, pos, 0, what)?;
239            let (extended_fault_type, pos) = decode_ctx_unsigned::<u32>(data, pos, 1, what)?;
240            let (raw_params, pos) = decode_ctx_constructed(data, pos, 2, what)?;
241            validate_extended_parameters(raw_params, "fault-extended")?;
242            let pos = expect_closing(data, pos, 2, what)?;
243            (
244                F::FaultExtended {
245                    vendor_id,
246                    extended_fault_type,
247                    parameters: raw_params.to_vec(),
248                },
249                pos,
250            )
251        }
252        3 => {
253            let mut pos = expect_opening(data, pos, 0, what)?;
254            let mut fault_values = Vec::new();
255            while !next_is_closing(data, pos, 0)? {
256                if fault_values.len() >= MAX_FRAMED_ITEMS {
257                    return Err(Error::overflow(
258                        pos,
259                        "fault-life-safety: list-of-fault-values exceeds limit",
260                    ));
261                }
262                let (v, p) = decode_app_enumerated::<u32>(data, pos, what)?;
263                fault_values.push(LifeSafetyState::from_raw(v));
264                pos = p;
265            }
266            pos = expect_closing(data, pos, 0, what)?;
267            pos = expect_opening(data, pos, 1, what)?;
268            let (mode_property_reference, p) = decode_dopr_body(data, pos, what)?;
269            pos = p;
270            pos = expect_closing(data, pos, 1, what)?;
271            pos = expect_closing(data, pos, 3, what)?;
272            (
273                F::FaultLifeSafety {
274                    fault_values,
275                    mode_property_reference,
276                },
277                pos,
278            )
279        }
280        4 => {
281            let mut pos = expect_opening(data, pos, 0, what)?;
282            let mut fault_values = Vec::new();
283            while !next_is_closing(data, pos, 0)? {
284                if fault_values.len() >= MAX_FRAMED_ITEMS {
285                    return Err(Error::overflow(
286                        pos,
287                        "fault-state: list-of-fault-values exceeds limit",
288                    ));
289                }
290                let (state, p) = decode_property_state(data, pos)?;
291                fault_values.push(state);
292                pos = p;
293            }
294            pos = expect_closing(data, pos, 0, what)?;
295            pos = expect_closing(data, pos, 4, what)?;
296            (F::FaultState { fault_values }, pos)
297        }
298        5 => {
299            let mut pos = expect_opening(data, pos, 0, what)?;
300            let (reference, p) = decode_dopr_body(data, pos, what)?;
301            pos = p;
302            pos = expect_closing(data, pos, 0, what)?;
303            pos = expect_closing(data, pos, 5, what)?;
304            (F::FaultStatusFlags { reference }, pos)
305        }
306        6 => {
307            let mut pos = expect_opening(data, pos, 0, what)?;
308            let (min_normal, p) = decode_fault_normal_value(data, pos)?;
309            pos = p;
310            pos = expect_closing(data, pos, 0, what)?;
311            pos = expect_opening(data, pos, 1, what)?;
312            let (max_normal, p) = decode_fault_normal_value(data, pos)?;
313            pos = p;
314            pos = expect_closing(data, pos, 1, what)?;
315            pos = expect_closing(data, pos, 6, what)?;
316            (
317                F::FaultOutOfRange {
318                    min_normal,
319                    max_normal,
320                },
321                pos,
322            )
323        }
324        7 => {
325            let mut pos = expect_opening(data, pos, 0, what)?;
326            let (reference, p) = decode_dopr_body(data, pos, what)?;
327            pos = p;
328            pos = expect_closing(data, pos, 0, what)?;
329            pos = expect_closing(data, pos, 7, what)?;
330            (F::FaultListed { reference }, pos)
331        }
332        n => {
333            return Err(Error::decoding(
334                offset,
335                format!("BACnetFaultParameter: unknown CHOICE tag [{n}]"),
336            ));
337        }
338    };
339    let (value, end) = value;
340    super::validate_tlv_sequence(&data[offset..end], what)?;
341    Ok((value, end))
342}
bacnet_encoding/constructed/fault_parameter.rs

bacnet_encoding/constructed/
fault_parameter.rs
