tinkerforge/bindings/
ambient_light_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 ambient light up to 900lux.
12//!
13//! See also the documentation [here](https://www.tinkerforge.com/en/doc/Software/Bricklets/AmbientLight_Bricklet_Rust.html).
14use crate::{
15    byte_converter::*, converting_callback_receiver::ConvertingCallbackReceiver, converting_receiver::ConvertingReceiver, device::*,
16    ip_connection::GetRequestSender,
17};
18pub enum AmbientLightBrickletFunction {
19    GetIlluminance,
20    GetAnalogValue,
21    SetIlluminanceCallbackPeriod,
22    GetIlluminanceCallbackPeriod,
23    SetAnalogValueCallbackPeriod,
24    GetAnalogValueCallbackPeriod,
25    SetIlluminanceCallbackThreshold,
26    GetIlluminanceCallbackThreshold,
27    SetAnalogValueCallbackThreshold,
28    GetAnalogValueCallbackThreshold,
29    SetDebouncePeriod,
30    GetDebouncePeriod,
31    GetIdentity,
32    CallbackIlluminance,
33    CallbackAnalogValue,
34    CallbackIlluminanceReached,
35    CallbackAnalogValueReached,
36}
37impl From<AmbientLightBrickletFunction> for u8 {
38    fn from(fun: AmbientLightBrickletFunction) -> Self {
39        match fun {
40            AmbientLightBrickletFunction::GetIlluminance => 1,
41            AmbientLightBrickletFunction::GetAnalogValue => 2,
42            AmbientLightBrickletFunction::SetIlluminanceCallbackPeriod => 3,
43            AmbientLightBrickletFunction::GetIlluminanceCallbackPeriod => 4,
44            AmbientLightBrickletFunction::SetAnalogValueCallbackPeriod => 5,
45            AmbientLightBrickletFunction::GetAnalogValueCallbackPeriod => 6,
46            AmbientLightBrickletFunction::SetIlluminanceCallbackThreshold => 7,
47            AmbientLightBrickletFunction::GetIlluminanceCallbackThreshold => 8,
48            AmbientLightBrickletFunction::SetAnalogValueCallbackThreshold => 9,
49            AmbientLightBrickletFunction::GetAnalogValueCallbackThreshold => 10,
50            AmbientLightBrickletFunction::SetDebouncePeriod => 11,
51            AmbientLightBrickletFunction::GetDebouncePeriod => 12,
52            AmbientLightBrickletFunction::GetIdentity => 255,
53            AmbientLightBrickletFunction::CallbackIlluminance => 13,
54            AmbientLightBrickletFunction::CallbackAnalogValue => 14,
55            AmbientLightBrickletFunction::CallbackIlluminanceReached => 15,
56            AmbientLightBrickletFunction::CallbackAnalogValueReached => 16,
57        }
58    }
59}
60pub const AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OFF: char = 'x';
61pub const AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OUTSIDE: char = 'o';
62pub const AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_INSIDE: char = 'i';
63pub const AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_SMALLER: char = '<';
64pub const AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_GREATER: char = '>';
65
66#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
67pub struct IlluminanceCallbackThreshold {
68    pub option: char,
69    pub min: u16,
70    pub max: u16,
71}
72impl FromByteSlice for IlluminanceCallbackThreshold {
73    fn bytes_expected() -> usize { 5 }
74    fn from_le_byte_slice(bytes: &[u8]) -> IlluminanceCallbackThreshold {
75        IlluminanceCallbackThreshold {
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 ambient light up to 900lux
124#[derive(Clone)]
125pub struct AmbientLightBricklet {
126    device: Device,
127}
128impl AmbientLightBricklet {
129    pub const DEVICE_IDENTIFIER: u16 = 21;
130    pub const DEVICE_DISPLAY_NAME: &'static str = "Ambient Light 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) -> AmbientLightBricklet {
133        let mut result = AmbientLightBricklet { device: Device::new([2, 0, 1], uid, req_sender, 0) };
134        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetIlluminance) as usize] = ResponseExpectedFlag::AlwaysTrue;
135        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetAnalogValue) as usize] = ResponseExpectedFlag::AlwaysTrue;
136        result.device.response_expected[u8::from(AmbientLightBrickletFunction::SetIlluminanceCallbackPeriod) as usize] =
137            ResponseExpectedFlag::True;
138        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetIlluminanceCallbackPeriod) as usize] =
139            ResponseExpectedFlag::AlwaysTrue;
140        result.device.response_expected[u8::from(AmbientLightBrickletFunction::SetAnalogValueCallbackPeriod) as usize] =
141            ResponseExpectedFlag::True;
142        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetAnalogValueCallbackPeriod) as usize] =
143            ResponseExpectedFlag::AlwaysTrue;
144        result.device.response_expected[u8::from(AmbientLightBrickletFunction::SetIlluminanceCallbackThreshold) as usize] =
145            ResponseExpectedFlag::True;
146        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetIlluminanceCallbackThreshold) as usize] =
147            ResponseExpectedFlag::AlwaysTrue;
148        result.device.response_expected[u8::from(AmbientLightBrickletFunction::SetAnalogValueCallbackThreshold) as usize] =
149            ResponseExpectedFlag::True;
150        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetAnalogValueCallbackThreshold) as usize] =
151            ResponseExpectedFlag::AlwaysTrue;
152        result.device.response_expected[u8::from(AmbientLightBrickletFunction::SetDebouncePeriod) as usize] = ResponseExpectedFlag::True;
153        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetDebouncePeriod) as usize] =
154            ResponseExpectedFlag::AlwaysTrue;
155        result.device.response_expected[u8::from(AmbientLightBrickletFunction::GetIdentity) as usize] = ResponseExpectedFlag::AlwaysTrue;
156        result
157    }
158
159    /// Returns the response expected flag for the function specified by the function ID parameter.
160    /// It is true if the function is expected to send a response, false otherwise.
161    ///
162    /// For getter functions this is enabled by default and cannot be disabled, because those
163    /// functions will always send a response. For callback configuration functions it is enabled
164    /// by default too, but can be disabled by [`set_response_expected`](crate::ambient_light_bricklet::AmbientLightBricklet::set_response_expected).
165    /// For setter functions it is disabled by default and can be enabled.
166    ///
167    /// Enabling the response expected flag for a setter function allows to detect timeouts
168    /// and other error conditions calls of this setter as well. The device will then send a response
169    /// for this purpose. If this flag is disabled for a setter function then no response is sent
170    /// and errors are silently ignored, because they cannot be detected.
171    ///
172    /// See [`set_response_expected`](crate::ambient_light_bricklet::AmbientLightBricklet::set_response_expected) for the list of function ID constants available for this function.
173    pub fn get_response_expected(&mut self, fun: AmbientLightBrickletFunction) -> Result<bool, GetResponseExpectedError> {
174        self.device.get_response_expected(u8::from(fun))
175    }
176
177    /// Changes the response expected flag of the function specified by the function ID parameter.
178    /// This flag can only be changed for setter (default value: false) and callback configuration
179    /// functions (default value: true). For getter functions it is always enabled.
180    ///
181    /// Enabling the response expected flag for a setter function allows to detect timeouts and
182    /// other error conditions calls of this setter as well. The device will then send a response
183    /// for this purpose. If this flag is disabled for a setter function then no response is sent
184    /// and errors are silently ignored, because they cannot be detected.
185    pub fn set_response_expected(
186        &mut self,
187        fun: AmbientLightBrickletFunction,
188        response_expected: bool,
189    ) -> Result<(), SetResponseExpectedError> {
190        self.device.set_response_expected(u8::from(fun), response_expected)
191    }
192
193    /// Changes the response expected flag for all setter and callback configuration functions of this device at once.
194    pub fn set_response_expected_all(&mut self, response_expected: bool) { self.device.set_response_expected_all(response_expected) }
195
196    /// Returns the version of the API definition (major, minor, revision) implemented by this API bindings.
197    /// This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.
198    pub fn get_api_version(&self) -> [u8; 3] { self.device.api_version }
199
200    /// This receiver is triggered periodically with the period that is set by
201    /// [`set_illuminance_callback_period`]. The parameter is the illuminance of the
202    /// ambient light sensor.
203    ///
204    /// The [`get_illuminance_callback_receiver`] receiver is only triggered if the illuminance has changed
205    /// since the last triggering.
206    ///
207    /// [`set_illuminance_callback_period`]: #method.set_illuminance_callback_period
208    /// [`get_illuminance_callback_receiver`]: #method.get_illuminance_callback_receiver
209    pub fn get_illuminance_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
210        self.device.get_callback_receiver(u8::from(AmbientLightBrickletFunction::CallbackIlluminance))
211    }
212
213    /// This receiver is triggered periodically with the period that is set by
214    /// [`set_analog_value_callback_period`]. The parameter is the analog value of the
215    /// ambient light sensor.
216    ///
217    /// The [`get_analog_value_callback_receiver`] receiver is only triggered if the analog value has
218    /// changed since the last triggering.
219    pub fn get_analog_value_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
220        self.device.get_callback_receiver(u8::from(AmbientLightBrickletFunction::CallbackAnalogValue))
221    }
222
223    /// This receiver is triggered when the threshold as set by
224    /// [`set_illuminance_callback_threshold`] is reached.
225    /// The parameter is the illuminance of the ambient light sensor.
226    ///
227    /// If the threshold keeps being reached, the receiver is triggered periodically
228    /// with the period as set by [`set_debounce_period`].
229    pub fn get_illuminance_reached_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
230        self.device.get_callback_receiver(u8::from(AmbientLightBrickletFunction::CallbackIlluminanceReached))
231    }
232
233    /// This receiver is triggered when the threshold as set by
234    /// [`set_analog_value_callback_threshold`] is reached.
235    /// The parameter is the analog value of the ambient light sensor.
236    ///
237    /// If the threshold keeps being reached, the receiver is triggered periodically
238    /// with the period as set by [`set_debounce_period`].
239    pub fn get_analog_value_reached_callback_receiver(&self) -> ConvertingCallbackReceiver<u16> {
240        self.device.get_callback_receiver(u8::from(AmbientLightBrickletFunction::CallbackAnalogValueReached))
241    }
242
243    /// Returns the illuminance of the ambient light sensor.
244    ///
245    /// If you want to get the illuminance periodically, it is recommended to use the
246    /// [`get_illuminance_callback_receiver`] receiver and set the period with
247    /// [`set_illuminance_callback_period`].
248    pub fn get_illuminance(&self) -> ConvertingReceiver<u16> {
249        let payload = vec![0; 0];
250
251        self.device.get(u8::from(AmbientLightBrickletFunction::GetIlluminance), payload)
252    }
253
254    /// Returns the value as read by a 12-bit analog-to-digital converter.
255    ///
256    /// # Note
257    ///  The value returned by [`get_illuminance`] is averaged over several samples
258    ///  to yield less noise, while [`get_analog_value`] gives back raw
259    ///  unfiltered analog values. The only reason to use [`get_analog_value`] is,
260    ///  if you need the full resolution of the analog-to-digital converter.
261    ///
262    ///  Also, the analog-to-digital converter covers three different ranges that are
263    ///  set dynamically depending on the light intensity. It is impossible to
264    ///  distinguish between these ranges with the analog value.
265    ///
266    /// If you want the analog value periodically, it is recommended to use the
267    /// [`get_analog_value_callback_receiver`] receiver and set the period with
268    /// [`set_analog_value_callback_period`].
269    pub fn get_analog_value(&self) -> ConvertingReceiver<u16> {
270        let payload = vec![0; 0];
271
272        self.device.get(u8::from(AmbientLightBrickletFunction::GetAnalogValue), payload)
273    }
274
275    /// Sets the period with which the [`get_illuminance_callback_receiver`] receiver is triggered
276    /// periodically. A value of 0 turns the receiver off.
277    ///
278    /// The [`get_illuminance_callback_receiver`] receiver is only triggered if the illuminance has changed
279    /// since the last triggering.
280    pub fn set_illuminance_callback_period(&self, period: u32) -> ConvertingReceiver<()> {
281        let mut payload = vec![0; 4];
282        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(period));
283
284        self.device.set(u8::from(AmbientLightBrickletFunction::SetIlluminanceCallbackPeriod), payload)
285    }
286
287    /// Returns the period as set by [`set_illuminance_callback_period`].
288    pub fn get_illuminance_callback_period(&self) -> ConvertingReceiver<u32> {
289        let payload = vec![0; 0];
290
291        self.device.get(u8::from(AmbientLightBrickletFunction::GetIlluminanceCallbackPeriod), payload)
292    }
293
294    /// Sets the period with which the [`get_analog_value_callback_receiver`] receiver is triggered
295    /// periodically. A value of 0 turns the receiver off.
296    ///
297    /// The [`get_analog_value_callback_receiver`] receiver is only triggered if the analog value has
298    /// changed since the last triggering.
299    pub fn set_analog_value_callback_period(&self, period: u32) -> ConvertingReceiver<()> {
300        let mut payload = vec![0; 4];
301        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(period));
302
303        self.device.set(u8::from(AmbientLightBrickletFunction::SetAnalogValueCallbackPeriod), payload)
304    }
305
306    /// Returns the period as set by [`set_analog_value_callback_period`].
307    pub fn get_analog_value_callback_period(&self) -> ConvertingReceiver<u32> {
308        let payload = vec![0; 0];
309
310        self.device.get(u8::from(AmbientLightBrickletFunction::GetAnalogValueCallbackPeriod), payload)
311    }
312
313    /// Sets the thresholds for the [`get_illuminance_reached_callback_receiver`] receiver.
314    ///
315    /// The following options are possible:
316    ///
317    ///  Option| Description
318    ///  --- | ---
319    ///  'x'|    Receiver is turned off
320    ///  'o'|    Receiver is triggered when the illuminance is *outside* the min and max values
321    ///  'i'|    Receiver is triggered when the illuminance is *inside* the min and max values
322    ///  '<'|    Receiver is triggered when the illuminance is smaller than the min value (max is ignored)
323    ///  '>'|    Receiver is triggered when the illuminance is greater than the min value (max is ignored)
324    ///
325    /// Associated constants:
326    /// * AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OFF
327    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OUTSIDE
328    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_INSIDE
329    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_SMALLER
330    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_GREATER
331    pub fn set_illuminance_callback_threshold(&self, option: char, min: u16, max: u16) -> ConvertingReceiver<()> {
332        let mut payload = vec![0; 5];
333        payload[0..1].copy_from_slice(&<char>::to_le_byte_vec(option));
334        payload[1..3].copy_from_slice(&<u16>::to_le_byte_vec(min));
335        payload[3..5].copy_from_slice(&<u16>::to_le_byte_vec(max));
336
337        self.device.set(u8::from(AmbientLightBrickletFunction::SetIlluminanceCallbackThreshold), payload)
338    }
339
340    /// Returns the threshold as set by [`set_illuminance_callback_threshold`].
341    ///
342    /// Associated constants:
343    /// * AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OFF
344    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OUTSIDE
345    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_INSIDE
346    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_SMALLER
347    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_GREATER
348    pub fn get_illuminance_callback_threshold(&self) -> ConvertingReceiver<IlluminanceCallbackThreshold> {
349        let payload = vec![0; 0];
350
351        self.device.get(u8::from(AmbientLightBrickletFunction::GetIlluminanceCallbackThreshold), payload)
352    }
353
354    /// Sets the thresholds for the [`get_analog_value_reached_callback_receiver`] receiver.
355    ///
356    /// The following options are possible:
357    ///
358    ///  Option| Description
359    ///  --- | ---
360    ///  'x'|    Receiver is turned off
361    ///  'o'|    Receiver is triggered when the analog value is *outside* the min and max values
362    ///  'i'|    Receiver is triggered when the analog value is *inside* the min and max values
363    ///  '<'|    Receiver is triggered when the analog value is smaller than the min value (max is ignored)
364    ///  '>'|    Receiver is triggered when the analog value is greater than the min value (max is ignored)
365    ///
366    /// Associated constants:
367    /// * AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OFF
368    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OUTSIDE
369    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_INSIDE
370    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_SMALLER
371    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_GREATER
372    pub fn set_analog_value_callback_threshold(&self, option: char, min: u16, max: u16) -> ConvertingReceiver<()> {
373        let mut payload = vec![0; 5];
374        payload[0..1].copy_from_slice(&<char>::to_le_byte_vec(option));
375        payload[1..3].copy_from_slice(&<u16>::to_le_byte_vec(min));
376        payload[3..5].copy_from_slice(&<u16>::to_le_byte_vec(max));
377
378        self.device.set(u8::from(AmbientLightBrickletFunction::SetAnalogValueCallbackThreshold), payload)
379    }
380
381    /// Returns the threshold as set by [`set_analog_value_callback_threshold`].
382    ///
383    /// Associated constants:
384    /// * AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OFF
385    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_OUTSIDE
386    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_INSIDE
387    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_SMALLER
388    ///	* AMBIENT_LIGHT_BRICKLET_THRESHOLD_OPTION_GREATER
389    pub fn get_analog_value_callback_threshold(&self) -> ConvertingReceiver<AnalogValueCallbackThreshold> {
390        let payload = vec![0; 0];
391
392        self.device.get(u8::from(AmbientLightBrickletFunction::GetAnalogValueCallbackThreshold), payload)
393    }
394
395    /// Sets the period with which the threshold receivers
396    ///
397    /// * [`get_illuminance_reached_callback_receiver`],
398    /// * [`get_analog_value_reached_callback_receiver`]
399    ///
400    /// are triggered, if the thresholds
401    ///
402    /// * [`set_illuminance_callback_threshold`],
403    /// * [`set_analog_value_callback_threshold`]
404    ///
405    /// keep being reached.
406    pub fn set_debounce_period(&self, debounce: u32) -> ConvertingReceiver<()> {
407        let mut payload = vec![0; 4];
408        payload[0..4].copy_from_slice(&<u32>::to_le_byte_vec(debounce));
409
410        self.device.set(u8::from(AmbientLightBrickletFunction::SetDebouncePeriod), payload)
411    }
412
413    /// Returns the debounce period as set by [`set_debounce_period`].
414    pub fn get_debounce_period(&self) -> ConvertingReceiver<u32> {
415        let payload = vec![0; 0];
416
417        self.device.get(u8::from(AmbientLightBrickletFunction::GetDebouncePeriod), payload)
418    }
419
420    /// Returns the UID, the UID where the Bricklet is connected to,
421    /// the position, the hardware and firmware version as well as the
422    /// device identifier.
423    ///
424    /// The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port).
425    /// A Bricklet connected to an [Isolator Bricklet](isolator_bricklet) is always at
426    /// position 'z'.
427    ///
428    /// The device identifier numbers can be found [here](device_identifier).
429    /// |device_identifier_constant|
430    pub fn get_identity(&self) -> ConvertingReceiver<Identity> {
431        let payload = vec![0; 0];
432
433        self.device.get(u8::from(AmbientLightBrickletFunction::GetIdentity), payload)
434    }
435}
tinkerforge/bindings/ambient_light_bricklet.rs

tinkerforge/bindings/
ambient_light_bricklet.rs
