tinkerforge/bindings/
humidity_bricklet.rs

1/* ***********************************************************
2 * This file was automatically generated on 2024-02-27.      *
3 *                                                           *
4 * Rust Bindings Version 2.0.21                              *
5 *                                                           *
6 * If you have a bugfix for this file and want to commit it, *
7 * please fix the bug in the generator. You can find a link  *
8 * to the generators git repository on tinkerforge.com       *
9 *************************************************************/
10
11//! Measures relative humidity.
12//!
13//! See also the documentation [here](https://www.tinkerforge.com/en/doc/Software/Bricklets/Humidity_Bricklet_Rust.html).
14use crate::{
15    byte_converter::*, converting_callback_receiver::ConvertingCallbackReceiver, converting_receiver::ConvertingReceiver, device::*,
16    ip_connection::GetRequestSender,
17};
18pub enum HumidityBrickletFunction {
19    GetHumidity,
20    GetAnalogValue,
21    SetHumidityCallbackPeriod,
22    GetHumidityCallbackPeriod,
23    SetAnalogValueCallbackPeriod,
24    GetAnalogValueCallbackPeriod,
25    SetHumidityCallbackThreshold,
26    GetHumidityCallbackThreshold,
27    SetAnalogValueCallbackThreshold,
28    GetAnalogValueCallbackThreshold,
29    SetDebouncePeriod,
30    GetDebouncePeriod,
31    GetIdentity,
32    CallbackHumidity,
33    CallbackAnalogValue,
34    CallbackHumidityReached,
35    CallbackAnalogValueReached,
36}
37impl From<HumidityBrickletFunction> for u8 {
38    fn from(fun: HumidityBrickletFunction) -> Self {
39        match fun {
40            HumidityBrickletFunction::GetHumidity => 1,
41            HumidityBrickletFunction::GetAnalogValue => 2,
42            HumidityBrickletFunction::SetHumidityCallbackPeriod => 3,
43            HumidityBrickletFunction::GetHumidityCallbackPeriod => 4,
44            HumidityBrickletFunction::SetAnalogValueCallbackPeriod => 5,
45            HumidityBrickletFunction::GetAnalogValueCallbackPeriod => 6,
46            HumidityBrickletFunction::SetHumidityCallbackThreshold => 7,
47            HumidityBrickletFunction::GetHumidityCallbackThreshold => 8,
48            HumidityBrickletFunction::SetAnalogValueCallbackThreshold => 9,
49            HumidityBrickletFunction::GetAnalogValueCallbackThreshold => 10,
50            HumidityBrickletFunction::SetDebouncePeriod => 11,
51            HumidityBrickletFunction::GetDebouncePeriod => 12,
52            HumidityBrickletFunction::GetIdentity => 255,
53            HumidityBrickletFunction::CallbackHumidity => 13,
54            HumidityBrickletFunction::CallbackAnalogValue => 14,
55            HumidityBrickletFunction::CallbackHumidityReached => 15,
56            HumidityBrickletFunction::CallbackAnalogValueReached => 16,
57        }
58    }
59}
60pub const HUMIDITY_BRICKLET_THRESHOLD_OPTION_OFF: char = 'x';
61pub const HUMIDITY_BRICKLET_THRESHOLD_OPTION_OUTSIDE: char = 'o';
62pub const HUMIDITY_BRICKLET_THRESHOLD_OPTION_INSIDE: char = 'i';
63pub const HUMIDITY_BRICKLET_THRESHOLD_OPTION_SMALLER: char = '<';
64pub const HUMIDITY_BRICKLET_THRESHOLD_OPTION_GREATER: char = '>';
65
66#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
67pub struct HumidityCallbackThreshold {
68    pub option: char,
69    pub min: u16,
70    pub max: u16,
71}
72impl FromByteSlice for HumidityCallbackThreshold {
73    fn bytes_expected() -> usize { 5 }
74    fn from_le_byte_slice(bytes: &[u8]) -> HumidityCallbackThreshold {
75        HumidityCallbackThreshold {
76            option: <char>::from_le_byte_slice(&bytes[0..1]),
77            min: <u16>::from_le_byte_slice(&bytes[1..3]),
78            max: <u16>::from_le_byte_slice(&bytes[3..5]),
79        }
80    }
81}
82
83#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
84pub struct AnalogValueCallbackThreshold {
85    pub option: char,
86    pub min: u16,
87    pub max: u16,
88}
89impl FromByteSlice for AnalogValueCallbackThreshold {
90    fn bytes_expected() -> usize { 5 }
91    fn from_le_byte_slice(bytes: &[u8]) -> AnalogValueCallbackThreshold {
92        AnalogValueCallbackThreshold {
93            option: <char>::from_le_byte_slice(&bytes[0..1]),
94            min: <u16>::from_le_byte_slice(&bytes[1..3]),
95            max: <u16>::from_le_byte_slice(&bytes[3..5]),
96        }
97    }
98}
99
100#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
101pub struct Identity {
102    pub uid: String,
103    pub connected_uid: String,
104    pub position: char,
105    pub hardware_version: [u8; 3],
106    pub firmware_version: [u8; 3],
107    pub device_identifier: u16,
108}
109impl FromByteSlice for Identity {
110    fn bytes_expected() -> usize { 25 }
111    fn from_le_byte_slice(bytes: &[u8]) -> Identity {
112        Identity {
113            uid: <String>::from_le_byte_slice(&bytes[0..8]),
114            connected_uid: <String>::from_le_byte_slice(&bytes[8..16]),
115            position: <char>::from_le_byte_slice(&bytes[16..17]),
116            hardware_version: <[u8; 3]>::from_le_byte_slice(&bytes[17..20]),
117            firmware_version: <[u8; 3]>::from_le_byte_slice(&bytes[20..23]),
118            device_identifier: <u16>::from_le_byte_slice(&bytes[23..25]),
119        }
120    }
121}
122
123/// Measures relative humidity
124#[derive(Clone)]
125pub struct HumidityBricklet {
126    device: Device,
127}
128impl HumidityBricklet {
129    pub const DEVICE_IDENTIFIER: u16 = 27;
130    pub const DEVICE_DISPLAY_NAME: &'static str = "Humidity Bricklet";
131    /// Creates an object with the unique device ID `uid`. This object can then be used after the IP Connection `ip_connection` is connected.
132    pub fn new<T: GetRequestSender>(uid: &str, req_sender: T) -> HumidityBricklet {
133        let mut result = HumidityBricklet { device: Device::new([2, 0, 1], uid, req_sender, 0) };
134        result.device.response_expected[u8::from(HumidityBrickletFunction::GetHumidity) as usize] = ResponseExpectedFlag::AlwaysTrue;
135        result.device.response_expected[u8::from(HumidityBrickletFunction::GetAnalogValue) as usize] = ResponseExpectedFlag::AlwaysTrue;
136        result.device.response_expected[u8::from(HumidityBrickletFunction::SetHumidityCallbackPeriod) as usize] =
137            ResponseExpectedFlag::True;
138        result.device.response_expected[u8::from(HumidityBrickletFunction::GetHumidityCallbackPeriod) as usize] =
139            ResponseExpectedFlag::AlwaysTrue;
140        result.device.response_expected[u8::from(HumidityBrickletFunction::SetAnalogValueCallbackPeriod) as usize] =
141            ResponseExpectedFlag::True;
142        result.device.response_expected[u8::from(HumidityBrickletFunction::GetAnalogValueCallbackPeriod) as usize] =
143            ResponseExpectedFlag::AlwaysTrue;
144        result.device.response_expected[u8::from(HumidityBrickletFunction::SetHumidityCallbackThreshold) as usize] =
145            ResponseExpectedFlag::True;
146        result.device.response_expected[u8::from(HumidityBrickletFunction::GetHumidityCallbackThreshold) as usize] =
147            ResponseExpectedFlag::AlwaysTrue;
148        result.device.response_expected[u8::from(HumidityBrickletFunction::SetAnalogValueCallbackThreshold) as usize] =
149            ResponseExpectedFlag::True;
150        result.device.response_expected[u8::from(HumidityBrickletFunction::GetAnalogValueCallbackThreshold) as usize] =
151            ResponseExpectedFlag::AlwaysTrue;
152        result.device.response_expected[u8::from(HumidityBrickletFunction::SetDebouncePeriod) as usize] = ResponseExpectedFlag::True;
153        result.device.response_expected[u8::from(HumidityBrickletFunction::GetDebouncePeriod) as usize] = ResponseExpectedFlag::AlwaysTrue;
154        result.device.response_expected[u8::from(HumidityBrickletFunction::GetIdentity) as usize] = ResponseExpectedFlag::AlwaysTrue;
155        result
156    }
157
158    /// Returns the response expected flag for the function specified by the function ID parameter.
159    /// It is true if the function is expected to send a response, false otherwise.
160    ///
161    /// For getter functions this is enabled by default and cannot be disabled, because those
162    /// functions will always send a response. For callback configuration functions it is enabled
163    /// by default too, but can be disabled by [`set_response_expected`](crate::humidity_bricklet::HumidityBricklet::set_response_expected).
164    /// For setter functions it is disabled by default and can be enabled.
165    ///
166    /// Enabling the response expected flag for a setter function allows to detect timeouts
167    /// and other error conditions calls of this setter as well. The device will then send a response
168    /// for this purpose. If this flag is disabled for a setter function then no response is sent
169    /// and errors are silently ignored, because they cannot be detected.
170    ///
171    /// See [`set_response_expected`](crate::humidity_bricklet::HumidityBricklet::set_response_expected) for the list of function ID constants available for this function.
172    pub fn get_response_expected(&mut self, fun: HumidityBrickletFunction) -> Result<bool, GetResponseExpectedError> {
173        self.device.get_response_expected(u8::from(fun))
174    }
175
176    /// Changes the response expected flag of the function specified by the function ID parameter.
177    /// This flag can only be changed for setter (default value: false) and callback configuration
178    /// functions (default value: true). For getter functions it is always enabled.
179    ///
180    /// Enabling the response expected flag for a setter function allows to detect timeouts and
181    /// other error conditions calls of this setter as well. The device will then send a response
182    /// for this purpose. If this flag is disabled for a setter function then no response is sent
183    /// and errors are silently ignored, because they cannot be detected.
184    pub fn set_response_expected(
185        &mut self,
186        fun: HumidityBrickletFunction,
187        response_expected: bool,
188    ) -> Result<(), SetResponseExpectedError> {
189        self.device.set_response_expected(u8::from(fun), response_expected)
190    }
191
192    /// Changes the response expected flag for all setter and callback configuration functions of this device at once.
193    pub fn set_response_expected_all(&mut self, response_expected: bool) { self.device.set_response_expected_all(response_expected) }
194
195    /// Returns the version of the API definition (major, minor, revision) implemented by this API bindings.
196    /// This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.
197    pub fn get_api_version(&self) -> [u8; 3] { self.device.api_version }
198
199    /// This receiver is triggered periodically with the period that is set by
200    /// [`set_humidity_callback_period`]. The parameter is the humidity of
201    /// the sensor.
202    ///
203    /// The [`get_humidity_callback_receiver`] receiver is only triggered if the humidity has changed since
204    /// the last triggering.
205    ///
206    /// [`set_humidity_callback_period`]: #method.set_humidity_callback_period
207    /// [`get_humidity_callback_receiver`]: #method.get_humidity_callback_receiver
208    pub fn get_humidity_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
209        self.device.get_callback_receiver(u8::from(HumidityBrickletFunction::CallbackHumidity))
210    }
211
212    /// This receiver is triggered periodically with the period that is set by
213    /// [`set_analog_value_callback_period`]. The parameter is the analog
214    /// value of the sensor.
215    ///
216    /// The [`get_analog_value_callback_receiver`] receiver is only triggered if the humidity has changed
217    /// since the last triggering.
218    pub fn get_analog_value_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
219        self.device.get_callback_receiver(u8::from(HumidityBrickletFunction::CallbackAnalogValue))
220    }
221
222    /// This receiver is triggered when the threshold as set by
223    /// [`set_humidity_callback_threshold`] is reached.
224    /// The parameter is the humidity of the sensor.
225    ///
226    /// If the threshold keeps being reached, the receiver is triggered periodically
227    /// with the period as set by [`set_debounce_period`].
228    pub fn get_humidity_reached_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
229        self.device.get_callback_receiver(u8::from(HumidityBrickletFunction::CallbackHumidityReached))
230    }
231
232    /// This receiver is triggered when the threshold as set by
233    /// [`set_analog_value_callback_threshold`] is reached.
234    /// The parameter is the analog value of the sensor.
235    ///
236    /// If the threshold keeps being reached, the receiver is triggered periodically
237    /// with the period as set by [`set_debounce_period`].
238    pub fn get_analog_value_reached_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
239        self.device.get_callback_receiver(u8::from(HumidityBrickletFunction::CallbackAnalogValueReached))
240    }
241
242    /// Returns the humidity of the sensor.
243    ///
244    /// If you want to get the humidity periodically, it is recommended to use the
245    /// [`get_humidity_callback_receiver`] receiver and set the period with
246    /// [`set_humidity_callback_period`].
247    pub fn get_humidity(&self) -> ConvertingReceiver<u16> {
248        let payload = vec![0; 0];
249
250        self.device.get(u8::from(HumidityBrickletFunction::GetHumidity), payload)
251    }
252
253    /// Returns the value as read by a 12-bit analog-to-digital converter.
254    ///
255    /// # Note
256    ///  The value returned by :func:[Get Humidity` is averaged over several samples
257    ///  to yield less noise, while [`get_analog_value`] gives back raw
258    ///  unfiltered analog values. The returned humidity value is calibrated for
259    ///  room temperatures, if you use the sensor in extreme cold or extreme
260    ///  warm environments, you might want to calculate the humidity from
261    ///  the analog value yourself. See the `HIH 5030 datasheet
262    /// ](https://github.com/Tinkerforge/humidity-bricklet/raw/master/datasheets/hih-5030.pdf)__.
263    ///
264    /// If you want the analog value periodically, it is recommended to use the
265    /// [`get_analog_value_callback_receiver`] receiver and set the period with
266    /// [`set_analog_value_callback_period`].
267    pub fn get_analog_value(&self) -> ConvertingReceiver<u16> {
268        let payload = vec![0; 0];
269
270        self.device.get(u8::from(HumidityBrickletFunction::GetAnalogValue), payload)
271    }
272
273    /// Sets the period with which the [`get_humidity_callback_receiver`] receiver is triggered
274    /// periodically. A value of 0 turns the receiver off.
275    ///
276    /// The [`get_humidity_callback_receiver`] receiver is only triggered if the humidity has changed
277    /// since the last triggering.
278    pub fn set_humidity_callback_period(&self, period: u32) -> ConvertingReceiver<()> {
279        let mut payload = vec![0; 4];
280        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(period));
281
282        self.device.set(u8::from(HumidityBrickletFunction::SetHumidityCallbackPeriod), payload)
283    }
284
285    /// Returns the period as set by [`set_humidity_callback_period`].
286    pub fn get_humidity_callback_period(&self) -> ConvertingReceiver<u32> {
287        let payload = vec![0; 0];
288
289        self.device.get(u8::from(HumidityBrickletFunction::GetHumidityCallbackPeriod), payload)
290    }
291
292    /// Sets the period with which the [`get_analog_value_callback_receiver`] receiver is triggered
293    /// periodically. A value of 0 turns the receiver off.
294    ///
295    /// The [`get_analog_value_callback_receiver`] receiver is only triggered if the analog value has
296    /// changed since the last triggering.
297    pub fn set_analog_value_callback_period(&self, period: u32) -> ConvertingReceiver<()> {
298        let mut payload = vec![0; 4];
299        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(period));
300
301        self.device.set(u8::from(HumidityBrickletFunction::SetAnalogValueCallbackPeriod), payload)
302    }
303
304    /// Returns the period as set by [`set_analog_value_callback_period`].
305    pub fn get_analog_value_callback_period(&self) -> ConvertingReceiver<u32> {
306        let payload = vec![0; 0];
307
308        self.device.get(u8::from(HumidityBrickletFunction::GetAnalogValueCallbackPeriod), payload)
309    }
310
311    /// Sets the thresholds for the [`get_humidity_reached_callback_receiver`] receiver.
312    ///
313    /// The following options are possible:
314    ///
315    ///  Option| Description
316    ///  --- | ---
317    ///  'x'|    Receiver is turned off
318    ///  'o'|    Receiver is triggered when the humidity is *outside* the min and max values
319    ///  'i'|    Receiver is triggered when the humidity is *inside* the min and max values
320    ///  '<'|    Receiver is triggered when the humidity is smaller than the min value (max is ignored)
321    ///  '>'|    Receiver is triggered when the humidity is greater than the min value (max is ignored)
322    ///
323    /// Associated constants:
324    /// * HUMIDITY_BRICKLET_THRESHOLD_OPTION_OFF
325    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_OUTSIDE
326    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_INSIDE
327    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_SMALLER
328    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_GREATER
329    pub fn set_humidity_callback_threshold(&self, option: char, min: u16, max: u16) -> ConvertingReceiver<()> {
330        let mut payload = vec![0; 5];
331        payload[0..1].copy_from_slice(&<char>::to_le_byte_vec(option));
332        payload[1..3].copy_from_slice(&<u16>::to_le_byte_vec(min));
333        payload[3..5].copy_from_slice(&<u16>::to_le_byte_vec(max));
334
335        self.device.set(u8::from(HumidityBrickletFunction::SetHumidityCallbackThreshold), payload)
336    }
337
338    /// Returns the threshold as set by [`set_humidity_callback_threshold`].
339    ///
340    /// Associated constants:
341    /// * HUMIDITY_BRICKLET_THRESHOLD_OPTION_OFF
342    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_OUTSIDE
343    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_INSIDE
344    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_SMALLER
345    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_GREATER
346    pub fn get_humidity_callback_threshold(&self) -> ConvertingReceiver<HumidityCallbackThreshold> {
347        let payload = vec![0; 0];
348
349        self.device.get(u8::from(HumidityBrickletFunction::GetHumidityCallbackThreshold), payload)
350    }
351
352    /// Sets the thresholds for the [`get_analog_value_reached_callback_receiver`] receiver.
353    ///
354    /// The following options are possible:
355    ///
356    ///  Option| Description
357    ///  --- | ---
358    ///  'x'|    Receiver is turned off
359    ///  'o'|    Receiver is triggered when the analog value is *outside* the min and max values
360    ///  'i'|    Receiver is triggered when the analog value is *inside* the min and max values
361    ///  '<'|    Receiver is triggered when the analog value is smaller than the min value (max is ignored)
362    ///  '>'|    Receiver is triggered when the analog value is greater than the min value (max is ignored)
363    ///
364    /// Associated constants:
365    /// * HUMIDITY_BRICKLET_THRESHOLD_OPTION_OFF
366    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_OUTSIDE
367    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_INSIDE
368    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_SMALLER
369    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_GREATER
370    pub fn set_analog_value_callback_threshold(&self, option: char, min: u16, max: u16) -> ConvertingReceiver<()> {
371        let mut payload = vec![0; 5];
372        payload[0..1].copy_from_slice(&<char>::to_le_byte_vec(option));
373        payload[1..3].copy_from_slice(&<u16>::to_le_byte_vec(min));
374        payload[3..5].copy_from_slice(&<u16>::to_le_byte_vec(max));
375
376        self.device.set(u8::from(HumidityBrickletFunction::SetAnalogValueCallbackThreshold), payload)
377    }
378
379    /// Returns the threshold as set by [`set_analog_value_callback_threshold`].
380    ///
381    /// Associated constants:
382    /// * HUMIDITY_BRICKLET_THRESHOLD_OPTION_OFF
383    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_OUTSIDE
384    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_INSIDE
385    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_SMALLER
386    ///	* HUMIDITY_BRICKLET_THRESHOLD_OPTION_GREATER
387    pub fn get_analog_value_callback_threshold(&self) -> ConvertingReceiver<AnalogValueCallbackThreshold> {
388        let payload = vec![0; 0];
389
390        self.device.get(u8::from(HumidityBrickletFunction::GetAnalogValueCallbackThreshold), payload)
391    }
392
393    /// Sets the period with which the threshold receivers
394    ///
395    /// * [`get_humidity_reached_callback_receiver`],
396    /// * [`get_analog_value_reached_callback_receiver`]
397    ///
398    /// are triggered, if the thresholds
399    ///
400    /// * [`set_humidity_callback_threshold`],
401    /// * [`set_analog_value_callback_threshold`]
402    ///
403    /// keep being reached.
404    pub fn set_debounce_period(&self, debounce: u32) -> ConvertingReceiver<()> {
405        let mut payload = vec![0; 4];
406        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(debounce));
407
408        self.device.set(u8::from(HumidityBrickletFunction::SetDebouncePeriod), payload)
409    }
410
411    /// Returns the debounce period as set by [`set_debounce_period`].
412    pub fn get_debounce_period(&self) -> ConvertingReceiver<u32> {
413        let payload = vec![0; 0];
414
415        self.device.get(u8::from(HumidityBrickletFunction::GetDebouncePeriod), payload)
416    }
417
418    /// Returns the UID, the UID where the Bricklet is connected to,
419    /// the position, the hardware and firmware version as well as the
420    /// device identifier.
421    ///
422    /// The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port).
423    /// A Bricklet connected to an [Isolator Bricklet](isolator_bricklet) is always at
424    /// position 'z'.
425    ///
426    /// The device identifier numbers can be found [here](device_identifier).
427    /// |device_identifier_constant|
428    pub fn get_identity(&self) -> ConvertingReceiver<Identity> {
429        let payload = vec![0; 0];
430
431        self.device.get(u8::from(HumidityBrickletFunction::GetIdentity), payload)
432    }
433}
tinkerforge/bindings/humidity_bricklet.rs

tinkerforge/bindings/
humidity_bricklet.rs
