tinkerforge_async/bindings/multi_touch_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//! Capacitive touch sensor for 12 electrodes.
12//!
13//! See also the documentation [here](https://www.tinkerforge.com/en/doc/Software/Bricklets/MultiTouch_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 MultiTouchBrickletFunction {
24 GetTouchState,
25 Recalibrate,
26 SetElectrodeConfig,
27 GetElectrodeConfig,
28 SetElectrodeSensitivity,
29 GetElectrodeSensitivity,
30 GetIdentity,
31 CallbackTouchState,
32}
33impl From<MultiTouchBrickletFunction> for u8 {
34 fn from(fun: MultiTouchBrickletFunction) -> Self {
35 match fun {
36 MultiTouchBrickletFunction::GetTouchState => 1,
37 MultiTouchBrickletFunction::Recalibrate => 2,
38 MultiTouchBrickletFunction::SetElectrodeConfig => 3,
39 MultiTouchBrickletFunction::GetElectrodeConfig => 4,
40 MultiTouchBrickletFunction::SetElectrodeSensitivity => 6,
41 MultiTouchBrickletFunction::GetElectrodeSensitivity => 7,
42 MultiTouchBrickletFunction::GetIdentity => 255,
43 MultiTouchBrickletFunction::CallbackTouchState => 5,
44 }
45 }
46}
47
48#[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
49pub struct Identity {
50 pub uid: String,
51 pub connected_uid: String,
52 pub position: char,
53 pub hardware_version: [u8; 3],
54 pub firmware_version: [u8; 3],
55 pub device_identifier: u16,
56}
57impl FromByteSlice for Identity {
58 fn bytes_expected() -> usize {
59 25
60 }
61 fn from_le_byte_slice(bytes: &[u8]) -> Identity {
62 Identity {
63 uid: <String>::from_le_byte_slice(&bytes[0..8]),
64 connected_uid: <String>::from_le_byte_slice(&bytes[8..16]),
65 position: <char>::from_le_byte_slice(&bytes[16..17]),
66 hardware_version: <[u8; 3]>::from_le_byte_slice(&bytes[17..20]),
67 firmware_version: <[u8; 3]>::from_le_byte_slice(&bytes[20..23]),
68 device_identifier: <u16>::from_le_byte_slice(&bytes[23..25]),
69 }
70 }
71}
72
73/// Capacitive touch sensor for 12 electrodes
74#[derive(Clone)]
75pub struct MultiTouchBricklet {
76 device: Device,
77}
78impl MultiTouchBricklet {
79 pub const DEVICE_IDENTIFIER: u16 = 234;
80 pub const DEVICE_DISPLAY_NAME: &'static str = "Multi Touch Bricklet";
81 /// Creates an object with the unique device ID `uid`. This object can then be used after the IP Connection `ip_connection` is connected.
82 pub fn new(uid: Uid, connection: AsyncIpConnection) -> MultiTouchBricklet {
83 let mut result = MultiTouchBricklet { device: Device::new([2, 0, 10], uid, connection, Self::DEVICE_DISPLAY_NAME) };
84 result.device.response_expected[u8::from(MultiTouchBrickletFunction::GetTouchState) as usize] = ResponseExpectedFlag::AlwaysTrue;
85 result.device.response_expected[u8::from(MultiTouchBrickletFunction::Recalibrate) as usize] = ResponseExpectedFlag::False;
86 result.device.response_expected[u8::from(MultiTouchBrickletFunction::SetElectrodeConfig) as usize] = ResponseExpectedFlag::False;
87 result.device.response_expected[u8::from(MultiTouchBrickletFunction::GetElectrodeConfig) as usize] =
88 ResponseExpectedFlag::AlwaysTrue;
89 result.device.response_expected[u8::from(MultiTouchBrickletFunction::SetElectrodeSensitivity) as usize] =
90 ResponseExpectedFlag::False;
91 result.device.response_expected[u8::from(MultiTouchBrickletFunction::GetElectrodeSensitivity) as usize] =
92 ResponseExpectedFlag::AlwaysTrue;
93 result.device.response_expected[u8::from(MultiTouchBrickletFunction::GetIdentity) as usize] = ResponseExpectedFlag::AlwaysTrue;
94 result
95 }
96
97 /// Returns the response expected flag for the function specified by the function ID parameter.
98 /// It is true if the function is expected to send a response, false otherwise.
99 ///
100 /// For getter functions this is enabled by default and cannot be disabled, because those
101 /// functions will always send a response. For callback configuration functions it is enabled
102 /// by default too, but can be disabled by [`set_response_expected`](crate::multi_touch_bricklet::MultiTouchBricklet::set_response_expected).
103 /// For setter functions it is disabled by default and can be enabled.
104 ///
105 /// Enabling the response expected flag for a setter function allows to detect timeouts
106 /// and other error conditions calls of this setter as well. The device will then send a response
107 /// for this purpose. If this flag is disabled for a setter function then no response is sent
108 /// and errors are silently ignored, because they cannot be detected.
109 ///
110 /// See [`set_response_expected`](crate::multi_touch_bricklet::MultiTouchBricklet::set_response_expected) for the list of function ID constants available for this function.
111 pub fn get_response_expected(&mut self, fun: MultiTouchBrickletFunction) -> Result<bool, GetResponseExpectedError> {
112 self.device.get_response_expected(u8::from(fun))
113 }
114
115 /// Changes the response expected flag of the function specified by the function ID parameter.
116 /// This flag can only be changed for setter (default value: false) and callback configuration
117 /// functions (default value: true). For getter functions it is always enabled.
118 ///
119 /// Enabling the response expected flag for a setter function allows to detect timeouts and
120 /// other error conditions calls of this setter as well. The device will then send a response
121 /// for this purpose. If this flag is disabled for a setter function then no response is sent
122 /// and errors are silently ignored, because they cannot be detected.
123 pub fn set_response_expected(
124 &mut self,
125 fun: MultiTouchBrickletFunction,
126 response_expected: bool,
127 ) -> Result<(), SetResponseExpectedError> {
128 self.device.set_response_expected(u8::from(fun), response_expected)
129 }
130
131 /// Changes the response expected flag for all setter and callback configuration functions of this device at once.
132 pub fn set_response_expected_all(&mut self, response_expected: bool) {
133 self.device.set_response_expected_all(response_expected)
134 }
135
136 /// Returns the version of the API definition (major, minor, revision) implemented by this API bindings.
137 /// This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.
138 pub fn get_api_version(&self) -> [u8; 3] {
139 self.device.api_version
140 }
141
142 /// Returns the current touch state, see [`get_touch_state`] for
143 /// information about the state.
144 ///
145 /// This receiver is triggered every time the touch state changes.
146 ///
147 /// [`get_touch_state`]: #method.get_touch_state
148 pub async fn get_touch_state_callback_receiver(&mut self) -> impl Stream<Item = u16> {
149 self.device
150 .get_callback_receiver(u8::from(MultiTouchBrickletFunction::CallbackTouchState))
151 .await
152 .map(|p| u16::from_le_byte_slice(p.body()))
153 }
154
155 /// Returns the current touch state. The state is given as a bitfield.
156 ///
157 /// Bits 0 to 11 represent the 12 electrodes and bit 12 represents
158 /// the proximity.
159 ///
160 /// If an electrode is touched, the corresponding bit is *true*. If
161 /// a hand or similar is in proximity to the electrodes, bit 12 is
162 /// *true*.
163 ///
164 /// Example: The state 4103 = 0x1007 = 0b1000000000111 means that
165 /// electrodes 0, 1 and 2 are touched and that something is in the
166 /// proximity of the electrodes.
167 ///
168 /// The proximity is activated with a distance of 1-2cm. An electrode
169 /// is already counted as touched if a finger is nearly touching the
170 /// electrode. This means that you can put a piece of paper or foil
171 /// or similar on top of a electrode to build a touch panel with
172 /// a professional look.
173 pub async fn get_touch_state(&mut self) -> Result<u16, TinkerforgeError> {
174 let payload = [0; 0];
175
176 #[allow(unused_variables)]
177 let result = self.device.get(u8::from(MultiTouchBrickletFunction::GetTouchState), &payload).await?;
178 Ok(u16::from_le_byte_slice(result.body()))
179 }
180
181 /// Recalibrates the electrodes. Call this function whenever you changed
182 /// or moved you electrodes.
183 pub async fn recalibrate(&mut self) -> Result<(), TinkerforgeError> {
184 let payload = [0; 0];
185
186 #[allow(unused_variables)]
187 let result = self.device.set(u8::from(MultiTouchBrickletFunction::Recalibrate), &payload).await?;
188 Ok(())
189 }
190
191 /// Enables/disables electrodes with a bitfield (see [`get_touch_state`]).
192 ///
193 /// *True* enables the electrode, *false* disables the electrode. A
194 /// disabled electrode will always return *false* as its state. If you
195 /// don't need all electrodes you can disable the electrodes that are
196 /// not needed.
197 ///
198 /// It is recommended that you disable the proximity bit (bit 12) if
199 /// the proximity feature is not needed. This will reduce the amount of
200 /// traffic that is produced by the [`get_touch_state_callback_receiver`] receiver.
201 ///
202 /// Disabling electrodes will also reduce power consumption.
203 ///
204 /// Default: 8191 = 0x1FFF = 0b1111111111111 (all electrodes and proximity feature enabled)
205 pub async fn set_electrode_config(&mut self, enabled_electrodes: u16) -> Result<(), TinkerforgeError> {
206 let mut payload = [0; 2];
207 enabled_electrodes.write_to_slice(&mut payload[0..2]);
208
209 #[allow(unused_variables)]
210 let result = self.device.set(u8::from(MultiTouchBrickletFunction::SetElectrodeConfig), &payload).await?;
211 Ok(())
212 }
213
214 /// Returns the electrode configuration, as set by [`set_electrode_config`].
215 pub async fn get_electrode_config(&mut self) -> Result<u16, TinkerforgeError> {
216 let payload = [0; 0];
217
218 #[allow(unused_variables)]
219 let result = self.device.get(u8::from(MultiTouchBrickletFunction::GetElectrodeConfig), &payload).await?;
220 Ok(u16::from_le_byte_slice(result.body()))
221 }
222
223 /// Sets the sensitivity of the electrodes. An electrode with a high sensitivity
224 /// will register a touch earlier then an electrode with a low sensitivity.
225 ///
226 /// If you build a big electrode you might need to decrease the sensitivity, since
227 /// the area that can be charged will get bigger. If you want to be able to
228 /// activate an electrode from further away you need to increase the sensitivity.
229 ///
230 /// After a new sensitivity is set, you likely want to call [`recalibrate`]
231 /// to calibrate the electrodes with the newly defined sensitivity.
232 pub async fn set_electrode_sensitivity(&mut self, sensitivity: u8) -> Result<(), TinkerforgeError> {
233 let mut payload = [0; 1];
234 sensitivity.write_to_slice(&mut payload[0..1]);
235
236 #[allow(unused_variables)]
237 let result = self.device.set(u8::from(MultiTouchBrickletFunction::SetElectrodeSensitivity), &payload).await?;
238 Ok(())
239 }
240
241 /// Returns the current sensitivity, as set by [`set_electrode_sensitivity`].
242 pub async fn get_electrode_sensitivity(&mut self) -> Result<u8, TinkerforgeError> {
243 let payload = [0; 0];
244
245 #[allow(unused_variables)]
246 let result = self.device.get(u8::from(MultiTouchBrickletFunction::GetElectrodeSensitivity), &payload).await?;
247 Ok(u8::from_le_byte_slice(result.body()))
248 }
249
250 /// Returns the UID, the UID where the Bricklet is connected to,
251 /// the position, the hardware and firmware version as well as the
252 /// device identifier.
253 ///
254 /// The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port).
255 /// A Bricklet connected to an [Isolator Bricklet](isolator_bricklet) is always at
256 /// position 'z'.
257 ///
258 /// The device identifier numbers can be found [here](device_identifier).
259 /// |device_identifier_constant|
260 pub async fn get_identity(&mut self) -> Result<Identity, TinkerforgeError> {
261 let payload = [0; 0];
262
263 #[allow(unused_variables)]
264 let result = self.device.get(u8::from(MultiTouchBrickletFunction::GetIdentity), &payload).await?;
265 Ok(Identity::from_le_byte_slice(result.body()))
266 }
267}