tinkerforge_async/bindings/
line_bricklet.rs

1/* ***********************************************************
2 * This file was automatically generated on 2024-02-16.      *
3 *                                                           *
4 * Rust Bindings Version 2.0.20                              *
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 reflectivity of a surface.
12//!
13//! See also the documentation [here](https://www.tinkerforge.com/en/doc/Software/Bricklets/Line_Bricklet_Rust.html).
14#[allow(unused_imports)]
15use crate::{
16    base58::Uid, byte_converter::*, device::*, error::TinkerforgeError, ip_connection::async_io::AsyncIpConnection,
17    low_level_traits::LowLevelRead,
18};
19#[allow(unused_imports)]
20use futures_core::Stream;
21#[allow(unused_imports)]
22use tokio_stream::StreamExt;
23pub enum LineBrickletFunction {
24    GetReflectivity,
25    SetReflectivityCallbackPeriod,
26    GetReflectivityCallbackPeriod,
27    SetReflectivityCallbackThreshold,
28    GetReflectivityCallbackThreshold,
29    SetDebouncePeriod,
30    GetDebouncePeriod,
31    GetIdentity,
32    CallbackReflectivity,
33    CallbackReflectivityReached,
34}
35impl From<LineBrickletFunction> for u8 {
36    fn from(fun: LineBrickletFunction) -> Self {
37        match fun {
38            LineBrickletFunction::GetReflectivity => 1,
39            LineBrickletFunction::SetReflectivityCallbackPeriod => 2,
40            LineBrickletFunction::GetReflectivityCallbackPeriod => 3,
41            LineBrickletFunction::SetReflectivityCallbackThreshold => 4,
42            LineBrickletFunction::GetReflectivityCallbackThreshold => 5,
43            LineBrickletFunction::SetDebouncePeriod => 6,
44            LineBrickletFunction::GetDebouncePeriod => 7,
45            LineBrickletFunction::GetIdentity => 255,
46            LineBrickletFunction::CallbackReflectivity => 8,
47            LineBrickletFunction::CallbackReflectivityReached => 9,
48        }
49    }
50}
51pub const LINE_BRICKLET_THRESHOLD_OPTION_OFF: char = 'x';
52pub const LINE_BRICKLET_THRESHOLD_OPTION_OUTSIDE: char = 'o';
53pub const LINE_BRICKLET_THRESHOLD_OPTION_INSIDE: char = 'i';
54pub const LINE_BRICKLET_THRESHOLD_OPTION_SMALLER: char = '<';
55pub const LINE_BRICKLET_THRESHOLD_OPTION_GREATER: char = '>';
56
57#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
58pub struct ReflectivityCallbackThreshold {
59    pub option: char,
60    pub min: u16,
61    pub max: u16,
62}
63impl FromByteSlice for ReflectivityCallbackThreshold {
64    fn bytes_expected() -> usize {
65        5
66    }
67    fn from_le_byte_slice(bytes: &[u8]) -> ReflectivityCallbackThreshold {
68        ReflectivityCallbackThreshold {
69            option: <char>::from_le_byte_slice(&bytes[0..1]),
70            min: <u16>::from_le_byte_slice(&bytes[1..3]),
71            max: <u16>::from_le_byte_slice(&bytes[3..5]),
72        }
73    }
74}
75
76#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
77pub struct Identity {
78    pub uid: String,
79    pub connected_uid: String,
80    pub position: char,
81    pub hardware_version: [u8; 3],
82    pub firmware_version: [u8; 3],
83    pub device_identifier: u16,
84}
85impl FromByteSlice for Identity {
86    fn bytes_expected() -> usize {
87        25
88    }
89    fn from_le_byte_slice(bytes: &[u8]) -> Identity {
90        Identity {
91            uid: <String>::from_le_byte_slice(&bytes[0..8]),
92            connected_uid: <String>::from_le_byte_slice(&bytes[8..16]),
93            position: <char>::from_le_byte_slice(&bytes[16..17]),
94            hardware_version: <[u8; 3]>::from_le_byte_slice(&bytes[17..20]),
95            firmware_version: <[u8; 3]>::from_le_byte_slice(&bytes[20..23]),
96            device_identifier: <u16>::from_le_byte_slice(&bytes[23..25]),
97        }
98    }
99}
100
101/// Measures reflectivity of a surface
102#[derive(Clone)]
103pub struct LineBricklet {
104    device: Device,
105}
106impl LineBricklet {
107    pub const DEVICE_IDENTIFIER: u16 = 241;
108    pub const DEVICE_DISPLAY_NAME: &'static str = "Line Bricklet";
109    /// Creates an object with the unique device ID `uid`. This object can then be used after the IP Connection `ip_connection` is connected.
110    pub fn new(uid: Uid, connection: AsyncIpConnection) -> LineBricklet {
111        let mut result = LineBricklet { device: Device::new([2, 0, 10], uid, connection, Self::DEVICE_DISPLAY_NAME) };
112        result.device.response_expected[u8::from(LineBrickletFunction::GetReflectivity) as usize] = ResponseExpectedFlag::AlwaysTrue;
113        result.device.response_expected[u8::from(LineBrickletFunction::SetReflectivityCallbackPeriod) as usize] =
114            ResponseExpectedFlag::True;
115        result.device.response_expected[u8::from(LineBrickletFunction::GetReflectivityCallbackPeriod) as usize] =
116            ResponseExpectedFlag::AlwaysTrue;
117        result.device.response_expected[u8::from(LineBrickletFunction::SetReflectivityCallbackThreshold) as usize] =
118            ResponseExpectedFlag::True;
119        result.device.response_expected[u8::from(LineBrickletFunction::GetReflectivityCallbackThreshold) as usize] =
120            ResponseExpectedFlag::AlwaysTrue;
121        result.device.response_expected[u8::from(LineBrickletFunction::SetDebouncePeriod) as usize] = ResponseExpectedFlag::True;
122        result.device.response_expected[u8::from(LineBrickletFunction::GetDebouncePeriod) as usize] = ResponseExpectedFlag::AlwaysTrue;
123        result.device.response_expected[u8::from(LineBrickletFunction::GetIdentity) as usize] = ResponseExpectedFlag::AlwaysTrue;
124        result
125    }
126
127    /// Returns the response expected flag for the function specified by the function ID parameter.
128    /// It is true if the function is expected to send a response, false otherwise.
129    ///
130    /// For getter functions this is enabled by default and cannot be disabled, because those
131    /// functions will always send a response. For callback configuration functions it is enabled
132    /// by default too, but can be disabled by [`set_response_expected`](crate::line_bricklet::LineBricklet::set_response_expected).
133    /// For setter functions it is disabled by default and can be enabled.
134    ///
135    /// Enabling the response expected flag for a setter function allows to detect timeouts
136    /// and other error conditions calls of this setter as well. The device will then send a response
137    /// for this purpose. If this flag is disabled for a setter function then no response is sent
138    /// and errors are silently ignored, because they cannot be detected.
139    ///
140    /// See [`set_response_expected`](crate::line_bricklet::LineBricklet::set_response_expected) for the list of function ID constants available for this function.
141    pub fn get_response_expected(&mut self, fun: LineBrickletFunction) -> Result<bool, GetResponseExpectedError> {
142        self.device.get_response_expected(u8::from(fun))
143    }
144
145    /// Changes the response expected flag of the function specified by the function ID parameter.
146    /// This flag can only be changed for setter (default value: false) and callback configuration
147    /// functions (default value: true). For getter functions it is always enabled.
148    ///
149    /// Enabling the response expected flag for a setter function allows to detect timeouts and
150    /// other error conditions calls of this setter as well. The device will then send a response
151    /// for this purpose. If this flag is disabled for a setter function then no response is sent
152    /// and errors are silently ignored, because they cannot be detected.
153    pub fn set_response_expected(&mut self, fun: LineBrickletFunction, response_expected: bool) -> Result<(), SetResponseExpectedError> {
154        self.device.set_response_expected(u8::from(fun), response_expected)
155    }
156
157    /// Changes the response expected flag for all setter and callback configuration functions of this device at once.
158    pub fn set_response_expected_all(&mut self, response_expected: bool) {
159        self.device.set_response_expected_all(response_expected)
160    }
161
162    /// Returns the version of the API definition (major, minor, revision) implemented by this API bindings.
163    /// This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.
164    pub fn get_api_version(&self) -> [u8; 3] {
165        self.device.api_version
166    }
167
168    /// This receiver is triggered periodically with the period that is set by
169    /// [`set_reflectivity_callback_period`]. The parameter is the
170    /// reflectivity of the sensor.
171    ///
172    /// The [`get_reflectivity_callback_receiver`] receiver is only triggered if the reflectivity has
173    /// changed since the last triggering.
174    ///
175    /// [`set_reflectivity_callback_period`]: #method.set_reflectivity_callback_period
176    /// [`get_reflectivity_callback_receiver`]: #method.get_reflectivity_callback_receiver
177    pub async fn get_reflectivity_callback_receiver(&mut self) -> impl Stream<Item = u16> {
178        self.device
179            .get_callback_receiver(u8::from(LineBrickletFunction::CallbackReflectivity))
180            .await
181            .map(|p| u16::from_le_byte_slice(p.body()))
182    }
183
184    /// This receiver is triggered when the threshold as set by
185    /// [`set_reflectivity_callback_threshold`] is reached.
186    /// The parameter is the reflectivity of the sensor.
187    ///
188    /// If the threshold keeps being reached, the receiver is triggered periodically
189    /// with the period as set by [`set_debounce_period`].
190    pub async fn get_reflectivity_reached_callback_receiver(&mut self) -> impl Stream<Item = u16> {
191        self.device
192            .get_callback_receiver(u8::from(LineBrickletFunction::CallbackReflectivityReached))
193            .await
194            .map(|p| u16::from_le_byte_slice(p.body()))
195    }
196
197    /// Returns the currently measured reflectivity. The reflectivity is
198    /// a value between 0 (not reflective) and 4095 (very reflective).
199    ///
200    /// Usually black has a low reflectivity while white has a high
201    /// reflectivity.
202    ///
203    /// If you want to get the reflectivity periodically, it is recommended
204    /// to use the [`get_reflectivity_callback_receiver`] receiver and set the period with
205    /// [`set_reflectivity_callback_period`].
206    pub async fn get_reflectivity(&mut self) -> Result<u16, TinkerforgeError> {
207        let payload = [0; 0];
208
209        #[allow(unused_variables)]
210        let result = self.device.get(u8::from(LineBrickletFunction::GetReflectivity), &payload).await?;
211        Ok(u16::from_le_byte_slice(result.body()))
212    }
213
214    /// Sets the period with which the [`get_reflectivity_callback_receiver`] receiver is triggered
215    /// periodically. A value of 0 turns the receiver off.
216    ///
217    /// The [`get_reflectivity_callback_receiver`] receiver is only triggered if the reflectivity has
218    /// changed since the last triggering.
219    pub async fn set_reflectivity_callback_period(&mut self, period: u32) -> Result<(), TinkerforgeError> {
220        let mut payload = [0; 4];
221        period.write_to_slice(&mut payload[0..4]);
222
223        #[allow(unused_variables)]
224        let result = self.device.set(u8::from(LineBrickletFunction::SetReflectivityCallbackPeriod), &payload).await?;
225        Ok(())
226    }
227
228    /// Returns the period as set by [`set_reflectivity_callback_period`].
229    pub async fn get_reflectivity_callback_period(&mut self) -> Result<u32, TinkerforgeError> {
230        let payload = [0; 0];
231
232        #[allow(unused_variables)]
233        let result = self.device.get(u8::from(LineBrickletFunction::GetReflectivityCallbackPeriod), &payload).await?;
234        Ok(u32::from_le_byte_slice(result.body()))
235    }
236
237    /// Sets the thresholds for the [`get_reflectivity_reached_callback_receiver`] receiver.
238    ///
239    /// The following options are possible:
240    ///
241    ///  Option| Description
242    ///  --- | ---
243    ///  'x'|    Receiver is turned off
244    ///  'o'|    Receiver is triggered when the reflectivity is *outside* the min and max values
245    ///  'i'|    Receiver is triggered when the reflectivity is *inside* the min and max values
246    ///  '<'|    Receiver is triggered when the reflectivity is smaller than the min value (max is ignored)
247    ///  '>'|    Receiver is triggered when the reflectivity is greater than the min value (max is ignored)
248    ///
249    /// Associated constants:
250    /// * LINE_BRICKLET_THRESHOLD_OPTION_OFF
251    ///	* LINE_BRICKLET_THRESHOLD_OPTION_OUTSIDE
252    ///	* LINE_BRICKLET_THRESHOLD_OPTION_INSIDE
253    ///	* LINE_BRICKLET_THRESHOLD_OPTION_SMALLER
254    ///	* LINE_BRICKLET_THRESHOLD_OPTION_GREATER
255    pub async fn set_reflectivity_callback_threshold(&mut self, option: char, min: u16, max: u16) -> Result<(), TinkerforgeError> {
256        let mut payload = [0; 5];
257        option.write_to_slice(&mut payload[0..1]);
258        min.write_to_slice(&mut payload[1..3]);
259        max.write_to_slice(&mut payload[3..5]);
260
261        #[allow(unused_variables)]
262        let result = self.device.set(u8::from(LineBrickletFunction::SetReflectivityCallbackThreshold), &payload).await?;
263        Ok(())
264    }
265
266    /// Returns the threshold as set by [`set_reflectivity_callback_threshold`].
267    ///
268    /// Associated constants:
269    /// * LINE_BRICKLET_THRESHOLD_OPTION_OFF
270    ///	* LINE_BRICKLET_THRESHOLD_OPTION_OUTSIDE
271    ///	* LINE_BRICKLET_THRESHOLD_OPTION_INSIDE
272    ///	* LINE_BRICKLET_THRESHOLD_OPTION_SMALLER
273    ///	* LINE_BRICKLET_THRESHOLD_OPTION_GREATER
274    pub async fn get_reflectivity_callback_threshold(&mut self) -> Result<ReflectivityCallbackThreshold, TinkerforgeError> {
275        let payload = [0; 0];
276
277        #[allow(unused_variables)]
278        let result = self.device.get(u8::from(LineBrickletFunction::GetReflectivityCallbackThreshold), &payload).await?;
279        Ok(ReflectivityCallbackThreshold::from_le_byte_slice(result.body()))
280    }
281
282    /// Sets the period with which the threshold receiver
283    ///
284    /// * [`get_reflectivity_reached_callback_receiver`]
285    ///
286    /// is triggered, if the threshold
287    ///
288    /// * [`set_reflectivity_callback_threshold`]
289    ///
290    /// keeps being reached.
291    pub async fn set_debounce_period(&mut self, debounce: u32) -> Result<(), TinkerforgeError> {
292        let mut payload = [0; 4];
293        debounce.write_to_slice(&mut payload[0..4]);
294
295        #[allow(unused_variables)]
296        let result = self.device.set(u8::from(LineBrickletFunction::SetDebouncePeriod), &payload).await?;
297        Ok(())
298    }
299
300    /// Returns the debounce period as set by [`set_debounce_period`].
301    pub async fn get_debounce_period(&mut self) -> Result<u32, TinkerforgeError> {
302        let payload = [0; 0];
303
304        #[allow(unused_variables)]
305        let result = self.device.get(u8::from(LineBrickletFunction::GetDebouncePeriod), &payload).await?;
306        Ok(u32::from_le_byte_slice(result.body()))
307    }
308
309    /// Returns the UID, the UID where the Bricklet is connected to,
310    /// the position, the hardware and firmware version as well as the
311    /// device identifier.
312    ///
313    /// The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port).
314    /// A Bricklet connected to an [Isolator Bricklet](isolator_bricklet) is always at
315    /// position 'z'.
316    ///
317    /// The device identifier numbers can be found [here](device_identifier).
318    /// |device_identifier_constant|
319    pub async fn get_identity(&mut self) -> Result<Identity, TinkerforgeError> {
320        let payload = [0; 0];
321
322        #[allow(unused_variables)]
323        let result = self.device.get(u8::from(LineBrickletFunction::GetIdentity), &payload).await?;
324        Ok(Identity::from_le_byte_slice(result.body()))
325    }
326}
tinkerforge_async/bindings/line_bricklet.rs

tinkerforge_async/bindings/
line_bricklet.rs
