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
//! This crate provides a userspace driver for the CANtact family of
//! Controller Area Network (CAN) devices.
//!
//! The rust library provided by this crate can be used directly to build
//! applications for CANtact. The crate also provides bindings for other
//! langauges.

#![warn(missing_docs)]

use std::fmt;
use std::sync::{Arc, RwLock};
use std::thread;

use crossbeam_channel::RecvError;

use serde::{Deserialize, Serialize};

mod device;
use device::gsusb::*;
use device::*;

pub mod c;
/// Implementation of Python bindings
#[cfg(feature = "python")]
pub mod python;

/// Errors generated by this library
#[derive(Debug)]
pub enum Error {
    /// Errors from device interaction.
    DeviceError(device::Error),
    /// The device could not be found, or the user does not have permissions to access it.
    DeviceNotFound,
    /// Timeout while communicating with the device.
    Timeout,
    /// Attempted to perform an action on a device that is running when this is not allowed.
    Running,
    /// Attempted to perform an action on a device that is not running when this is not allowed.
    NotRunning,
    /// Requested channel index does not exist on device.
    InvalidChannel,
    /// The requested bitrate cannot be set within an acceptable tolerance
    InvalidBitrate(u32),
}
impl From<device::Error> for Error {
    fn from(e: device::Error) -> Error {
        // TODO
        // this could do a much better job of converting
        Error::DeviceError(e)
    }
}

/// Controller Area Network Frame
#[derive(Debug, Clone)]
pub struct Frame {
    /// CAN frame arbitration ID.
    pub can_id: u32,

    /// CAN frame Data Length Code (DLC).
    pub can_dlc: u8,

    /// Device channel used to send or receive the frame.
    pub channel: u8,

    /// Frame data contents.
    pub data: [u8; 8],

    /// Extended (29 bit) arbitration identifier if true,
    /// standard (11 bit) arbitration identifer if false.
    pub ext: bool,

    /// CAN Flexible Data (CAN-FD) frame flag.
    pub fd: bool,

    /// Loopback flag. When true, frame was sent by this device/channel.
    /// False for received frames.
    pub loopback: bool,

    /// Remote Transmission Request (RTR) flag.
    pub rtr: bool,
}
impl Frame {
    // convert to a frame format expected by the device
    fn to_host_frame(&self) -> HostFrame {
        // if frame is extended, set the extended bit in host frame CAN ID
        let mut can_id = if self.ext {
            self.can_id | GSUSB_EXT_FLAG
        } else {
            self.can_id
        };
        // if frame is RTR, set the RTR bit in host frame CAN ID
        can_id = if self.rtr {
            can_id | GSUSB_RTR_FLAG
        } else {
            can_id
        };
        HostFrame {
            echo_id: 1,
            flags: 0,
            reserved: 0,
            can_id,
            can_dlc: self.can_dlc,
            channel: self.channel,
            data: self.data,
        }
    }
    /// Returns a default CAN frame with all values set to zero/false.
    pub fn default() -> Frame {
        Frame {
            can_id: 0,
            can_dlc: 0,
            data: [0u8; 8],
            channel: 0,
            ext: false,
            fd: false,
            loopback: false,
            rtr: false,
        }
    }
    fn from_host_frame(hf: HostFrame) -> Frame {
        // check the extended bit of host frame
        // if set, frame is extended
        let ext = (hf.can_id & GSUSB_EXT_FLAG) > 0;
        // check the RTR bit of host frame
        // if set, frame is RTR
        let rtr = (hf.can_id & GSUSB_RTR_FLAG) > 0;
        // remove flags from CAN ID
        let can_id = hf.can_id & 0x3FFF_FFFF;
        // loopback frame if echo_id is not -1
        let loopback = hf.echo_id != GSUSB_RX_ECHO_ID;
        Frame {
            can_id,
            can_dlc: hf.can_dlc,
            data: hf.data,
            channel: hf.channel,
            ext,
            loopback,
            rtr,
            fd: false, //TODO
        }
    }
}

/// Configuration for a device's CAN channel.
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Channel {
    /// Bitrate of the channel in bits/second
    pub bitrate: u32,
    /// When true, channel should be enabled when device starts
    pub enabled: bool,
    /// When true, device is configured in hardware loopback mode
    pub loopback: bool,
    /// When true, device will not transmit on the bus.
    pub monitor: bool,
}

/// Interface for interacting with CANtact devices
pub struct Interface {
    dev: Device,
    running: Arc<RwLock<bool>>,

    can_clock: u32,
    // zero indexed (0 = 1 channel, 1 = 2 channels, etc...)
    channel_count: usize,
    sw_version: u32,
    hw_version: u32,

    channels: Vec<Channel>,
}

impl fmt::Debug for Interface {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Interface")
            .field("running", &(*self.running.read().unwrap()))
            .field("can_clock", &self.can_clock)
            .field("channel_count", &self.channel_count)
            .field("sw_version", &self.sw_version)
            .field("hw_version", &self.hw_version)
            .field("channels", &self.channels)
            .finish()
    }
}

impl Interface {
    /// Creates a new interface. This always selects the first device found by
    /// libusb. If no device is found, Error::DeviceNotFound is returned.
    pub fn new() -> Result<Interface, Error> {
        let mut dev = match Device::new(UsbContext::new()) {
            Ok(d) => d,
            Err(_) => return Err(Error::DeviceNotFound),
        };

        let dev_config = dev.get_device_config()?;
        let bt_consts = dev.get_bit_timing_consts()?;

        let channel_count = dev_config.icount as usize;

        let mut channels = Vec::new();
        // note: channel_count is zero indexed
        for _ in 0..(channel_count + 1) {
            channels.push(Channel {
                bitrate: 0,
                enabled: true,
                loopback: false,
                monitor: false,
            });
        }

        let i = Interface {
            dev,
            running: Arc::new(RwLock::from(false)),

            channel_count,
            can_clock: bt_consts.fclk_can,
            sw_version: dev_config.sw_version,
            hw_version: dev_config.hw_version,

            channels,
        };

        Ok(i)
    }

    /// Start CAN communication on all configured channels.
    ///
    /// After starting the device, `Interface.send` can be used to send frames.
    /// For every received frame, the `rx_callback` closure will be called.
    pub fn start(
        &mut self,
        mut rx_callback: impl FnMut(Frame) + Sync + Send + 'static,
    ) -> Result<(), Error> {
        // tell the device to go on bus
        for (i, ch) in self.channels.iter().enumerate() {
            let mut flags = 0;
            if ch.monitor {
                flags |= GSUSB_FEATURE_LISTEN_ONLY;
            }
            if ch.loopback {
                flags |= GSUSB_FEATURE_LOOP_BACK;
            }

            let mode = Mode {
                mode: CanMode::Start as u32,
                flags,
            };
            if ch.enabled {
                self.dev.set_mode(i as u16, mode).unwrap();
            }
        }

        {
            *self.running.write().unwrap() = true;
        }

        // rx callback thread
        let can_rx = self.dev.can_rx_recv.clone();
        let running = Arc::clone(&self.running);
        thread::spawn(move || {
            while *running.read().unwrap() {
                match can_rx.recv() {
                    Ok(hf) => rx_callback(Frame::from_host_frame(hf)),
                    Err(RecvError) => {
                        // channel disconnected
                        break;
                    }
                }
            }
        });

        self.dev.start_transfers().unwrap();
        Ok(())
    }

    /// Stop CAN communication on all channels.
    pub fn stop(&mut self) -> Result<(), Error> {
        // TODO multi-channel
        for (i, ch) in self.channels.iter().enumerate() {
            let mode = Mode {
                mode: CanMode::Reset as u32,
                flags: 0,
            };
            if ch.enabled {
                self.dev.set_mode(i as u16, mode).unwrap();
            }
        }

        self.dev.stop_transfers().unwrap();

        *self.running.write().unwrap() = false;
        Ok(())
    }

    /// Set bitrate for specified channel to requested bitrate value in bits per second.
    pub fn set_bitrate(&mut self, channel: usize, bitrate: u32) -> Result<(), Error> {
        if channel > self.channel_count {
            return Err(Error::InvalidChannel);
        }

        let bt = calculate_bit_timing(self.can_clock, bitrate)?;
        self.dev
            .set_bit_timing(channel as u16, bt)
            .expect("failed to set bit timing");

        self.channels[channel].bitrate = bitrate;
        Ok(())
    }

    /// Enable or disable a channel's listen only mode. When this mode is enabled,
    /// the device will not transmit any frames, errors, or acknowledgements.
    pub fn set_monitor(&mut self, channel: usize, enabled: bool) -> Result<(), Error> {
        if channel > self.channel_count {
            return Err(Error::InvalidChannel);
        }
        if *self.running.read().unwrap() {
            return Err(Error::Running);
        }

        self.channels[channel].monitor = enabled;
        Ok(())
    }

    /// Enable or disable a channel's listen only mode. When this mode is enabled,
    /// the device will not transmit any frames, errors, or acknowledgements.
    pub fn set_enabled(&mut self, channel: usize, enabled: bool) -> Result<(), Error> {
        if channel > self.channel_count {
            return Err(Error::InvalidChannel);
        }
        if *self.running.read().unwrap() {
            return Err(Error::Running);
        }

        self.channels[channel].enabled = enabled;
        Ok(())
    }

    /// Enable or disable a channel's loopback mode. When this mode is enabled,
    /// frames sent by the device will be received by the device
    /// *as if they had been sent by another node on the bus*.
    ///
    /// This mode is primarily intended for device testing!
    pub fn set_loopback(&mut self, channel: usize, enabled: bool) -> Result<(), Error> {
        if channel > self.channel_count {
            return Err(Error::InvalidChannel);
        }
        if *self.running.read().unwrap() {
            return Err(Error::Running);
        }

        self.channels[channel].loopback = enabled;
        Ok(())
    }

    /// Send a CAN frame using the device
    pub fn send(&mut self, f: Frame) -> Result<(), Error> {
        if !*self.running.read().unwrap() {
            return Err(Error::NotRunning);
        }

        self.dev.send(f.to_host_frame()).unwrap();
        Ok(())
    }

    /// Returns the number of channels this Interface has
    pub fn channels(&self) -> usize {
        self.channel_count + 1
    }
}

fn calculate_bit_timing(clk: u32, bitrate: u32) -> Result<BitTiming, Error> {
    let max_brp = 32;
    let min_seg1 = 3;
    let max_seg1 = 18;
    let min_seg2 = 2;
    let max_seg2 = 8;
    let tolerances = vec![0.0, 0.1 / 100.0, 0.5 / 100.0];

    for tolerance in tolerances {
        let tmp = clk as f32 / bitrate as f32;
        for brp in 1..(max_brp + 1) {
            let btq = tmp / brp as f32;
            let btq_rounded = btq.round() as u32;

            if btq_rounded >= 4 && btq_rounded <= 32 {
                let err = ((btq / (btq_rounded as f32) - 1.0) * 10000.0).round() / 10000.0;
                if err.abs() > tolerance {
                    // error is not acceptable
                    continue;
                }
            }

            for seg1 in min_seg1..max_seg1 {
                // subtract 1 from seg2 to account for propagation phase
                let seg2 = btq_rounded - seg1 - 1;
                if seg2 < min_seg2 || seg2 > max_seg2 {
                    // invalid seg2 value
                    continue;
                }
                // brp, seg1, and seg2 are all valid
                return Ok(BitTiming {
                    brp,
                    prop_seg: 0,
                    phase_seg1: seg1,
                    phase_seg2: seg2,
                    sjw: 1,
                });
            }
        }
    }
    Err(Error::InvalidBitrate(bitrate))
}

#[allow(dead_code)]
fn effective_bitrate(clk: u32, bt: BitTiming) -> u32 {
    clk / bt.brp / (bt.prop_seg + bt.phase_seg1 + bt.phase_seg2 + 1)
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn test_bit_timing() {
        let clk = 48000000;
        let bitrates = vec![1000000, 500000, 250000, 125000];
        for b in bitrates {
            let bt = calculate_bit_timing(clk, b).unwrap();

            // ensure error < 0.5%
            let err = 100.0 * (1.0 - (effective_bitrate(clk, bt) as f32 / b as f32).abs());
            assert!(err < 0.5);
        }
    }
}