1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
// Licensed under the Apache License, Version 2.0 or the MIT License.
// SPDX-License-Identifier: Apache-2.0 OR MIT
// Copyright Tock Contributors 2022.

//! Interface for sending and receiving IEEE 802.15.4 packets.
//!
//! Hardware independent interface for an 802.15.4 radio. Note that
//! configuration commands are asynchronous and must be committed with a call to
//! config_commit. For example, calling set_address will change the source
//! address of packets but does not change the address stored in hardware used
//! for address recognition. This must be committed to hardware with a call to
//! config_commit. Please see the relevant TRD for more details.

use crate::ErrorCode;

/// Client trait for when sending a packet is finished.
pub trait TxClient {
    /// Send is complete or an error occurred during transmission.
    ///
    /// ## Arguments
    ///
    /// - `buf`: Buffer of the transmitted packet.
    /// - `acked`: Set to true if the sender received an acknowledgement after
    ///   transmitting. Note, this is only set on a confirmed ACK; if the
    ///   transmission did not request an ACK this will be set to false.
    /// - `result`: Status of the transmission. `Ok(())` when the packet was
    ///   sent successfully. On `Err()`, valid errors are:
    ///   - `ErrorCode::BUSY`: The channel was never clear and we could not
    ///     transmit.
    ///   - `ErrorCode::FAIL`: Internal TX error occurred.
    fn send_done(&self, buf: &'static mut [u8], acked: bool, result: Result<(), ErrorCode>);
}

/// Client for receiving packets.
pub trait RxClient {
    /// Packet was received.
    ///
    /// ## Arguments
    ///
    /// - `buf`: Buffer containing the packet. This is the buffer provided via
    ///   `RadioData::set_receive_buffer()`. The structure of this buffer is the
    ///   same as in the TX case, as described in this HIL. That is, the first
    ///   byte is reserved, and the full 802.15.4 starts with the PHR in the
    ///   second byte.
    /// - `frame_len`: Length of the received frame, excluding the MAC footer.
    ///   In other words, this length is PHR-MFR_SIZE. Note, this length does
    ///   _not_ correspond to the length of data from the start of the buffer.
    ///   This length is from the third byte in the buffer (i.e.,
    ///   `buf[2:2+frame_length]`).
    /// - `lqi`: The Link Quality Indicator as measured by the receiver during
    ///   the packet reception. This is on the scale as specified in the IEEE
    ///   802.15.4 specification (section 6.9.8), with value 0 being the lowest
    ///   detectable signal and value 0xff as the highest quality detectable
    ///   signal.
    /// - `crc_valid`: Whether the CRC check matched the received frame. Note,
    ///   the MFR bytes are not required to be stored in `buf` so using this
    ///   argument is the only reliable method for checking the CRC.
    /// - `result`: Status of the reception. `Ok(())` when the packet was
    ///   received normally. On `Err()`, valid errors are:
    ///   - `ErrorCode::NOMEM`: Ack was requested, but there was no buffer
    ///     available to transmit an ACK.
    ///   - `ErrorCode::FAIL`: Internal error occurred.
    fn receive(
        &self,
        buf: &'static mut [u8],
        frame_len: usize,
        lqi: u8,
        crc_valid: bool,
        result: Result<(), ErrorCode>,
    );
}

/// Client for callbacks after the radio is configured.
pub trait ConfigClient {
    /// Configuring the radio has finished.
    ///
    /// ## Arguments
    ///
    /// - `result`: Status of the configuration procedure. `Ok(())` if all
    ///   options were set as expected. On `Err()`, valid errors are:
    ///   - `ErrorCode::FAIL`: Internal error occurred.
    fn config_done(&self, result: Result<(), ErrorCode>);
}

/// Client for callbacks when the radio's power state changes.
pub trait PowerClient {
    /// The power state of the radio changed. This is called when the radio has
    /// turned on or off.
    ///
    /// ## Arguments
    ///
    /// - `on`: True if the radio is now on. False otherwise.
    fn changed(&self, on: bool);
}

// These constants are used for interacting with the SPI buffer, which contains
// a 1-byte SPI command, a 1-byte PHY header, and then the 802.15.4 frame. In
// theory, the number of extra bytes in front of the frame can depend on the
// particular method used to communicate with the radio, but we leave this as a
// constant in this generic trait for now.
//
// Furthermore, the minimum MHR size assumes that
//
// - The source PAN ID is omitted
// - There is no auxiliary security header
// - There are no IEs
//
// ```text
// +---------+-----+--------+-------------+-----+-----+
// | SPI com | PHR | MHR    | MAC payload | MFR | LQI |
// +---------+-----+--------+-------------+-----+-----+
// \______ Static buffer for implementation __________/
//                 \_________ PSDU _____________/
// \___ 2 bytes ___/                            \1byte/
// ```

/// Length of the physical layer header. This is the Frame length field.
pub const PHR_SIZE: usize = 1;
/// Length of the Frame Control field in the MAC header.
pub const MHR_FC_SIZE: usize = 2;
/// Length of the MAC footer. Contains the CRC.
pub const MFR_SIZE: usize = 2;
/// Maximum length of a MAC frame.
pub const MAX_MTU: usize = 127;
/// Minimum length of the MAC frame (except for acknowledgements). This is
/// explained in Table 21 of the specification.
pub const MIN_FRAME_SIZE: usize = 9;
/// Maximum length of a MAC frame.
pub const MAX_FRAME_SIZE: usize = MAX_MTU;

/// Location in the buffer of the physical layer header. This is the location of
/// the Frame length byte.
pub const PHR_OFFSET: usize = 1;
/// Location in the buffer of the PSDU. This is equivalent to the start of the
/// MAC payload.
pub const PSDU_OFFSET: usize = 2;
/// Length of the reserved space in the buffer for a SPI command.
pub const SPI_HEADER_SIZE: usize = 1;
/// Length of the reserved space in the buffer for LQI information.
pub const LQI_SIZE: usize = 1;
/// Required buffer size for implementations of this HIL.
pub const MAX_BUF_SIZE: usize = SPI_HEADER_SIZE + PHR_SIZE + MAX_MTU + LQI_SIZE;

/// General Radio trait that supports configuration and TX/RX.
pub trait Radio<'a>: RadioConfig<'a> + RadioData<'a> {}
// Provide blanket implementations for trait group
impl<'a, T: RadioConfig<'a> + RadioData<'a>> Radio<'a> for T {}

/// Configure the 802.15.4 radio.
pub trait RadioConfig<'a> {
    /// Initialize the radio.
    ///
    /// This should perform any needed initialization, but should not turn the
    /// radio on.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn initialize(&self) -> Result<(), ErrorCode>;

    /// Reset the radio.
    ///
    /// Perform a radio reset which may reset the internal state of the radio.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn reset(&self) -> Result<(), ErrorCode>;

    /// Start the radio.
    ///
    /// This should put the radio into receive mode.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn start(&self) -> Result<(), ErrorCode>;

    /// Stop the radio.
    ///
    /// This should turn the radio off, disabling receive mode, and put the
    /// radio into a low power state.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn stop(&self) -> Result<(), ErrorCode>;

    /// Check if the radio is currently on.
    ///
    /// ## Return
    ///
    /// True if the radio is on, false otherwise.
    fn is_on(&self) -> bool;

    /// Check if the radio is currently busy transmitting or receiving a packet.
    ///
    /// If this returns `true`, the radio is unable to start another operation.
    ///
    /// ## Return
    ///
    /// True if the radio is busy, false otherwise.
    fn busy(&self) -> bool;

    /// Set the client that is called when the radio changes power states.
    fn set_power_client(&self, client: &'a dyn PowerClient);

    /// Commit the configuration calls to the radio.
    ///
    /// This will set the address, PAN ID, TX power, and channel to the
    /// specified values within the radio hardware. When this finishes, this
    /// will issue a callback to the config client when done.
    fn config_commit(&self);

    /// Set the client that is called when configuration finishes.
    fn set_config_client(&self, client: &'a dyn ConfigClient);

    /// Get the 802.15.4 short (16-bit) address for the radio.
    ///
    /// ## Return
    ///
    /// The radio's short address.
    fn get_address(&self) -> u16;

    /// Get the 802.15.4 extended (64-bit) address for the radio.
    ///
    /// ## Return
    ///
    /// The radio's extended address.
    fn get_address_long(&self) -> [u8; 8];

    /// Get the 802.15.4 16-bit PAN ID for the radio.
    ///
    /// ## Return
    ///
    /// The radio's PAN ID.
    fn get_pan(&self) -> u16;

    /// Get the radio's transmit power.
    ///
    /// ## Return
    ///
    /// The transmit power setting used by the radio, in dBm.
    fn get_tx_power(&self) -> i8;

    /// Get the 802.15.4 channel the radio is currently using.
    ///
    /// ## Return
    ///
    /// The channel number.
    fn get_channel(&self) -> u8;

    /// Set the 802.15.4 short (16-bit) address for the radio.
    ///
    /// Note, calling this function configures the software driver, but does not
    /// take effect in the radio hardware. Call `RadioConfig::config_commit()`
    /// to set the configuration settings in the radio hardware.
    ///
    /// ## Argument
    ///
    /// - `addr`: The short address.
    fn set_address(&self, addr: u16);

    /// Set the 802.15.4 extended (64-bit) address for the radio.
    ///
    /// Note, calling this function configures the software driver, but does not
    /// take effect in the radio hardware. Call `RadioConfig::config_commit()`
    /// to set the configuration settings in the radio hardware.
    ///
    /// ## Argument
    ///
    /// - `addr`: The extended address.
    fn set_address_long(&self, addr: [u8; 8]);

    /// Set the 802.15.4 PAN ID (16-bit) for the radio.
    ///
    /// Note, calling this function configures the software driver, but does not
    /// take effect in the radio hardware. Call `RadioConfig::config_commit()`
    /// to set the configuration settings in the radio hardware.
    ///
    /// ## Argument
    ///
    /// - `id`: The PAN ID.
    fn set_pan(&self, id: u16);

    /// Set the radio's transmit power.
    ///
    /// Note, calling this function configures the software driver, but does not
    /// take effect in the radio hardware. Call `RadioConfig::config_commit()`
    /// to set the configuration settings in the radio hardware.
    ///
    /// ## Argument
    ///
    /// - `power`: The transmit power in dBm.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::INVAL`: The transmit power is above acceptable limits.
    /// - `ErrorCode::NOSUPPORT`: The transmit power is not supported by the
    ///   radio.
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn set_tx_power(&self, power: i8) -> Result<(), ErrorCode>;

    /// Set the 802.15.4 channel for the radio.
    ///
    /// Note, calling this function configures the software driver, but does not
    /// take effect in the radio hardware. Call `RadioConfig::config_commit()`
    /// to set the configuration settings in the radio hardware.
    ///
    /// ## Argument
    ///
    /// - `chan`: The 802.15.4 channel.
    fn set_channel(&self, chan: RadioChannel);
}

/// Send and receive packets with the 802.15.4 radio.
pub trait RadioData<'a> {
    /// Set the client that will be called when packets are transmitted.
    fn set_transmit_client(&self, client: &'a dyn TxClient);

    /// Set the client that will be called when packets are received.
    fn set_receive_client(&self, client: &'a dyn RxClient);

    /// Set the buffer to receive packets into.
    ///
    /// ## Argument
    ///
    /// - `receive_buffer`: The buffer to receive into. Must be at least
    ///   `MAX_BUF_SIZE` bytes long.
    fn set_receive_buffer(&self, receive_buffer: &'static mut [u8]);

    /// Transmit a packet.
    ///
    /// The radio will create and insert the PHR (Frame length) field.
    ///
    /// ## Argument
    ///
    /// - `buf`: Buffer with the MAC layer 802.15.4 frame to be transmitted.
    ///   The buffer must conform to the buffer formatted documented in the HIL.
    ///   That is, the MAC payload (PSDU) must start at the third byte.
    ///   The first byte must be reserved for the radio driver (i.e.
    ///   for a SPI transaction) and the second byte is reserved for the PHR.
    ///   The buffer must be at least `frame_len` + 2 + MFR_SIZE` bytes long.
    /// - `frame_len`: The length of the MAC payload, not including the MFR.
    ///
    /// ## Return
    ///
    /// `Ok(())` on success. On `Err()`, valid errors are:
    ///
    /// - `ErrorCode::OFF`: The radio is off and cannot transmit.
    /// - `ErrorCode::BUSY`: The radio is busy. This is likely to occur because
    ///   the radio is already transmitting a packet.
    /// - `ErrorCode::SIZE`: The buffer does not have room for the MFR (CRC).
    /// - `ErrorCode::FAIL`: Internal error occurred.
    fn transmit(
        &self,
        buf: &'static mut [u8],
        frame_len: usize,
    ) -> Result<(), (ErrorCode, &'static mut [u8])>;
}

/// IEEE 802.15.4 valid channels.
#[derive(PartialEq, Debug, Copy, Clone)]
pub enum RadioChannel {
    Channel11 = 5,
    Channel12 = 10,
    Channel13 = 15,
    Channel14 = 20,
    Channel15 = 25,
    Channel16 = 30,
    Channel17 = 35,
    Channel18 = 40,
    Channel19 = 45,
    Channel20 = 50,
    Channel21 = 55,
    Channel22 = 60,
    Channel23 = 65,
    Channel24 = 70,
    Channel25 = 75,
    Channel26 = 80,
}

impl RadioChannel {
    /// Get the IEEE 802.15.4 channel number for the `RadioChannel`.
    ///
    /// ## Return
    ///
    /// A 1 byte number corresponding to the channel number.
    pub fn get_channel_number(&self) -> u8 {
        match *self {
            RadioChannel::Channel11 => 11,
            RadioChannel::Channel12 => 12,
            RadioChannel::Channel13 => 13,
            RadioChannel::Channel14 => 14,
            RadioChannel::Channel15 => 15,
            RadioChannel::Channel16 => 16,
            RadioChannel::Channel17 => 17,
            RadioChannel::Channel18 => 18,
            RadioChannel::Channel19 => 19,
            RadioChannel::Channel20 => 20,
            RadioChannel::Channel21 => 21,
            RadioChannel::Channel22 => 22,
            RadioChannel::Channel23 => 23,
            RadioChannel::Channel24 => 24,
            RadioChannel::Channel25 => 25,
            RadioChannel::Channel26 => 26,
        }
    }
}

impl TryFrom<u8> for RadioChannel {
    type Error = ();
    /// Try to convert a 1 byte channel number to a `RadioChannel`
    ///
    /// ## Argument
    ///
    /// - `val`: The channel number to convert.
    ///
    /// ## Return
    ///
    /// Returns `Ok(RadioChannel)` if `val` is a valid IEEE 802.15.4 2.4 GHz
    /// channel number. Otherwise, returns `Err(())`.
    fn try_from(val: u8) -> Result<RadioChannel, ()> {
        match val {
            11 => Ok(RadioChannel::Channel11),
            12 => Ok(RadioChannel::Channel12),
            13 => Ok(RadioChannel::Channel13),
            14 => Ok(RadioChannel::Channel14),
            15 => Ok(RadioChannel::Channel15),
            16 => Ok(RadioChannel::Channel16),
            17 => Ok(RadioChannel::Channel17),
            18 => Ok(RadioChannel::Channel18),
            19 => Ok(RadioChannel::Channel19),
            20 => Ok(RadioChannel::Channel20),
            21 => Ok(RadioChannel::Channel21),
            22 => Ok(RadioChannel::Channel22),
            23 => Ok(RadioChannel::Channel23),
            24 => Ok(RadioChannel::Channel24),
            25 => Ok(RadioChannel::Channel25),
            26 => Ok(RadioChannel::Channel26),
            _ => Err(()),
        }
    }
}