tinkerforge/bindings/industrial_quad_relay_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//! 4 galvanically isolated solid state relays.
12//!
13//! See also the documentation [here](https://www.tinkerforge.com/en/doc/Software/Bricklets/IndustrialQuadRelay_Bricklet_Rust.html).
14use crate::{
15 byte_converter::*, converting_callback_receiver::ConvertingCallbackReceiver, converting_receiver::ConvertingReceiver, device::*,
16 ip_connection::GetRequestSender,
17};
18pub enum IndustrialQuadRelayBrickletFunction {
19 SetValue,
20 GetValue,
21 SetMonoflop,
22 GetMonoflop,
23 SetGroup,
24 GetGroup,
25 GetAvailableForGroup,
26 SetSelectedValues,
27 GetIdentity,
28 CallbackMonoflopDone,
29}
30impl From<IndustrialQuadRelayBrickletFunction> for u8 {
31 fn from(fun: IndustrialQuadRelayBrickletFunction) -> Self {
32 match fun {
33 IndustrialQuadRelayBrickletFunction::SetValue => 1,
34 IndustrialQuadRelayBrickletFunction::GetValue => 2,
35 IndustrialQuadRelayBrickletFunction::SetMonoflop => 3,
36 IndustrialQuadRelayBrickletFunction::GetMonoflop => 4,
37 IndustrialQuadRelayBrickletFunction::SetGroup => 5,
38 IndustrialQuadRelayBrickletFunction::GetGroup => 6,
39 IndustrialQuadRelayBrickletFunction::GetAvailableForGroup => 7,
40 IndustrialQuadRelayBrickletFunction::SetSelectedValues => 9,
41 IndustrialQuadRelayBrickletFunction::GetIdentity => 255,
42 IndustrialQuadRelayBrickletFunction::CallbackMonoflopDone => 8,
43 }
44 }
45}
46
47#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
48pub struct Monoflop {
49 pub value: u16,
50 pub time: u32,
51 pub time_remaining: u32,
52}
53impl FromByteSlice for Monoflop {
54 fn bytes_expected() -> usize { 10 }
55 fn from_le_byte_slice(bytes: &[u8]) -> Monoflop {
56 Monoflop {
57 value: <u16>::from_le_byte_slice(&bytes[0..2]),
58 time: <u32>::from_le_byte_slice(&bytes[2..6]),
59 time_remaining: <u32>::from_le_byte_slice(&bytes[6..10]),
60 }
61 }
62}
63
64#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
65pub struct MonoflopDoneEvent {
66 pub selection_mask: u16,
67 pub value_mask: u16,
68}
69impl FromByteSlice for MonoflopDoneEvent {
70 fn bytes_expected() -> usize { 4 }
71 fn from_le_byte_slice(bytes: &[u8]) -> MonoflopDoneEvent {
72 MonoflopDoneEvent { selection_mask: <u16>::from_le_byte_slice(&bytes[0..2]), value_mask: <u16>::from_le_byte_slice(&bytes[2..4]) }
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 { 25 }
87 fn from_le_byte_slice(bytes: &[u8]) -> Identity {
88 Identity {
89 uid: <String>::from_le_byte_slice(&bytes[0..8]),
90 connected_uid: <String>::from_le_byte_slice(&bytes[8..16]),
91 position: <char>::from_le_byte_slice(&bytes[16..17]),
92 hardware_version: <[u8; 3]>::from_le_byte_slice(&bytes[17..20]),
93 firmware_version: <[u8; 3]>::from_le_byte_slice(&bytes[20..23]),
94 device_identifier: <u16>::from_le_byte_slice(&bytes[23..25]),
95 }
96 }
97}
98
99/// 4 galvanically isolated solid state relays
100#[derive(Clone)]
101pub struct IndustrialQuadRelayBricklet {
102 device: Device,
103}
104impl IndustrialQuadRelayBricklet {
105 pub const DEVICE_IDENTIFIER: u16 = 225;
106 pub const DEVICE_DISPLAY_NAME: &'static str = "Industrial Quad Relay Bricklet";
107 /// Creates an object with the unique device ID `uid`. This object can then be used after the IP Connection `ip_connection` is connected.
108 pub fn new<T: GetRequestSender>(uid: &str, req_sender: T) -> IndustrialQuadRelayBricklet {
109 let mut result = IndustrialQuadRelayBricklet { device: Device::new([2, 0, 0], uid, req_sender, 0) };
110 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::SetValue) as usize] = ResponseExpectedFlag::False;
111 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::GetValue) as usize] =
112 ResponseExpectedFlag::AlwaysTrue;
113 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::SetMonoflop) as usize] = ResponseExpectedFlag::False;
114 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::GetMonoflop) as usize] =
115 ResponseExpectedFlag::AlwaysTrue;
116 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::SetGroup) as usize] = ResponseExpectedFlag::False;
117 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::GetGroup) as usize] =
118 ResponseExpectedFlag::AlwaysTrue;
119 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::GetAvailableForGroup) as usize] =
120 ResponseExpectedFlag::AlwaysTrue;
121 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::SetSelectedValues) as usize] =
122 ResponseExpectedFlag::False;
123 result.device.response_expected[u8::from(IndustrialQuadRelayBrickletFunction::GetIdentity) as usize] =
124 ResponseExpectedFlag::AlwaysTrue;
125 result
126 }
127
128 /// Returns the response expected flag for the function specified by the function ID parameter.
129 /// It is true if the function is expected to send a response, false otherwise.
130 ///
131 /// For getter functions this is enabled by default and cannot be disabled, because those
132 /// functions will always send a response. For callback configuration functions it is enabled
133 /// by default too, but can be disabled by [`set_response_expected`](crate::industrial_quad_relay_bricklet::IndustrialQuadRelayBricklet::set_response_expected).
134 /// For setter functions it is disabled by default and can be enabled.
135 ///
136 /// Enabling the response expected flag for a setter function allows to detect timeouts
137 /// and other error conditions calls of this setter as well. The device will then send a response
138 /// for this purpose. If this flag is disabled for a setter function then no response is sent
139 /// and errors are silently ignored, because they cannot be detected.
140 ///
141 /// See [`set_response_expected`](crate::industrial_quad_relay_bricklet::IndustrialQuadRelayBricklet::set_response_expected) for the list of function ID constants available for this function.
142 pub fn get_response_expected(&mut self, fun: IndustrialQuadRelayBrickletFunction) -> Result<bool, GetResponseExpectedError> {
143 self.device.get_response_expected(u8::from(fun))
144 }
145
146 /// Changes the response expected flag of the function specified by the function ID parameter.
147 /// This flag can only be changed for setter (default value: false) and callback configuration
148 /// functions (default value: true). For getter functions it is always enabled.
149 ///
150 /// Enabling the response expected flag for a setter function allows to detect timeouts and
151 /// other error conditions calls of this setter as well. The device will then send a response
152 /// for this purpose. If this flag is disabled for a setter function then no response is sent
153 /// and errors are silently ignored, because they cannot be detected.
154 pub fn set_response_expected(
155 &mut self,
156 fun: IndustrialQuadRelayBrickletFunction,
157 response_expected: bool,
158 ) -> Result<(), SetResponseExpectedError> {
159 self.device.set_response_expected(u8::from(fun), response_expected)
160 }
161
162 /// Changes the response expected flag for all setter and callback configuration functions of this device at once.
163 pub fn set_response_expected_all(&mut self, response_expected: bool) { self.device.set_response_expected_all(response_expected) }
164
165 /// Returns the version of the API definition (major, minor, revision) implemented by this API bindings.
166 /// This is neither the release version of this API bindings nor does it tell you anything about the represented Brick or Bricklet.
167 pub fn get_api_version(&self) -> [u8; 3] { self.device.api_version }
168
169 /// This receiver is triggered whenever a monoflop timer reaches 0. The
170 /// parameters contain the involved pins and the current value of the pins
171 /// (the value after the monoflop).
172 pub fn get_monoflop_done_callback_receiver(&self) -> ConvertingCallbackReceiver<MonoflopDoneEvent> {
173 self.device.get_callback_receiver(u8::from(IndustrialQuadRelayBrickletFunction::CallbackMonoflopDone))
174 }
175
176 /// Sets the output value with a bitmask (16bit). A 1 in the bitmask means relay
177 /// closed and a 0 means relay open.
178 ///
179 /// For example: The value 3 or 0b0011 will close the relay of pins 0-1 and open
180 /// the other pins.
181 ///
182 /// If no groups are used (see [`set_group`]), the pins correspond to the
183 /// markings on the Industrial Quad Relay Bricklet.
184 ///
185 /// If groups are used, the pins correspond to the element in the group.
186 /// Element 1 in the group will get pins 0-3, element 2 pins 4-7, element 3
187 /// pins 8-11 and element 4 pins 12-15.
188 ///
189 /// All running monoflop timers will be aborted if this function is called.
190 pub fn set_value(&self, value_mask: u16) -> ConvertingReceiver<()> {
191 let mut payload = vec![0; 2];
192 payload[0..2].copy_from_slice(&<u16>::to_le_byte_vec(value_mask));
193
194 self.device.set(u8::from(IndustrialQuadRelayBrickletFunction::SetValue), payload)
195 }
196
197 /// Returns the bitmask as set by [`set_value`].
198 pub fn get_value(&self) -> ConvertingReceiver<u16> {
199 let payload = vec![0; 0];
200
201 self.device.get(u8::from(IndustrialQuadRelayBrickletFunction::GetValue), payload)
202 }
203
204 /// Configures a monoflop of the pins specified by the first parameter
205 /// bitmask.
206 ///
207 /// The second parameter is a bitmask with the desired value of the specified
208 /// pins. A 1 in the bitmask means relay closed and a 0 means relay open.
209 ///
210 /// The third parameter indicates the time that the pins should hold
211 /// the value.
212 ///
213 /// If this function is called with the parameters (9, 1, 1500) or
214 /// (0b1001, 0b0001, 1500): Pin 0 will close and pin 3 will open. In 1.5s pin 0
215 /// will open and pin 3 will close again.
216 ///
217 /// A monoflop can be used as a fail-safe mechanism. For example: Lets assume you
218 /// have a RS485 bus and a Quad Relay Bricklet connected to one of the slave
219 /// stacks. You can now call this function every second, with a time parameter
220 /// of two seconds and pin 0 closed. Pin 0 will be closed all the time. If now
221 /// the RS485 connection is lost, then pin 0 will be opened in at most two seconds.
222 pub fn set_monoflop(&self, selection_mask: u16, value_mask: u16, time: u32) -> ConvertingReceiver<()> {
223 let mut payload = vec![0; 8];
224 payload[0..2].copy_from_slice(&<u16>::to_le_byte_vec(selection_mask));
225 payload[2..4].copy_from_slice(&<u16>::to_le_byte_vec(value_mask));
226 payload[4..8].copy_from_slice(&<u32>::to_le_byte_vec(time));
227
228 self.device.set(u8::from(IndustrialQuadRelayBrickletFunction::SetMonoflop), payload)
229 }
230
231 /// Returns (for the given pin) the current value and the time as set by
232 /// [`set_monoflop`] as well as the remaining time until the value flips.
233 ///
234 /// If the timer is not running currently, the remaining time will be returned
235 /// as 0.
236 pub fn get_monoflop(&self, pin: u8) -> ConvertingReceiver<Monoflop> {
237 let mut payload = vec![0; 1];
238 payload[0..1].copy_from_slice(&<u8>::to_le_byte_vec(pin));
239
240 self.device.get(u8::from(IndustrialQuadRelayBrickletFunction::GetMonoflop), payload)
241 }
242
243 /// Sets a group of Quad Relay Bricklets that should work together. You can
244 /// find Bricklets that can be grouped together with [`get_available_for_group`].
245 ///
246 /// The group consists of 4 elements. Element 1 in the group will get pins 0-3,
247 /// element 2 pins 4-7, element 3 pins 8-11 and element 4 pins 12-15.
248 ///
249 /// Each element can either be one of the ports ('a' to 'd') or 'n' if it should
250 /// not be used.
251 ///
252 /// For example: If you have two Quad Relay Bricklets connected to port A and
253 /// port B respectively, you could call with ``['a', 'b', 'n', 'n']``.
254 ///
255 /// Now the pins on the Quad Relay on port A are assigned to 0-3 and the
256 /// pins on the Quad Relay on port B are assigned to 4-7. It is now possible
257 /// to call [`set_value`] and control two Bricklets at the same time.
258 pub fn set_group(&self, group: [char; 4]) -> ConvertingReceiver<()> {
259 let mut payload = vec![0; 4];
260 payload[0..4].copy_from_slice(&<[char; 4]>::to_le_byte_vec(group));
261
262 self.device.set(u8::from(IndustrialQuadRelayBrickletFunction::SetGroup), payload)
263 }
264
265 /// Returns the group as set by [`set_group`]
266 pub fn get_group(&self) -> ConvertingReceiver<[char; 4]> {
267 let payload = vec![0; 0];
268
269 self.device.get(u8::from(IndustrialQuadRelayBrickletFunction::GetGroup), payload)
270 }
271
272 /// Returns a bitmask of ports that are available for grouping. For example the
273 /// value 5 or 0b0101 means: Port A and port C are connected to Bricklets that
274 /// can be grouped together.
275 pub fn get_available_for_group(&self) -> ConvertingReceiver<u8> {
276 let payload = vec![0; 0];
277
278 self.device.get(u8::from(IndustrialQuadRelayBrickletFunction::GetAvailableForGroup), payload)
279 }
280
281 /// Sets the output value with a bitmask, according to the selection mask.
282 /// The bitmask is 16 bit long, *true* refers to a closed relay and
283 /// *false* refers to an open relay.
284 ///
285 /// For example: The values (3, 1) or (0b0011, 0b0001) will close the relay of
286 /// pin 0, open the relay of pin 1 and leave the others untouched.
287 ///
288 /// If no groups are used (see [`set_group`]), the pins correspond to the
289 /// markings on the Industrial Quad Relay Bricklet.
290 ///
291 /// If groups are used, the pins correspond to the element in the group.
292 /// Element 1 in the group will get pins 0-3, element 2 pins 4-7, element 3
293 /// pins 8-11 and element 4 pins 12-15.
294 ///
295 /// Running monoflop timers for the selected relays will be aborted if this function
296 /// is called.
297 pub fn set_selected_values(&self, selection_mask: u16, value_mask: u16) -> ConvertingReceiver<()> {
298 let mut payload = vec![0; 4];
299 payload[0..2].copy_from_slice(&<u16>::to_le_byte_vec(selection_mask));
300 payload[2..4].copy_from_slice(&<u16>::to_le_byte_vec(value_mask));
301
302 self.device.set(u8::from(IndustrialQuadRelayBrickletFunction::SetSelectedValues), payload)
303 }
304
305 /// Returns the UID, the UID where the Bricklet is connected to,
306 /// the position, the hardware and firmware version as well as the
307 /// device identifier.
308 ///
309 /// The position can be 'a', 'b', 'c', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port).
310 /// A Bricklet connected to an [Isolator Bricklet](isolator_bricklet) is always at
311 /// position 'z'.
312 ///
313 /// The device identifier numbers can be found [here](device_identifier).
314 /// |device_identifier_constant|
315 pub fn get_identity(&self) -> ConvertingReceiver<Identity> {
316 let payload = vec![0; 0];
317
318 self.device.get(u8::from(IndustrialQuadRelayBrickletFunction::GetIdentity), payload)
319 }
320}