Struct cc1101_rust::CC1101

pub struct CC1101 { /* private fields */ }

CC1101 radio device

This struct provides a handle to a CC1101 device, presented by the Linux Driver as a character device (e.g /dev/cc1101.0.0). It is used to configure the driver to receive and transmit packets.

Receive

As all packet reception and interaction with the CC1101 hardware occurs within the kernel driver, receiving packets is an asynchronous process.

The driver begins RX when an IOCTL is sent to the character device with a receive configuration. Packets received by the radio are buffered within a FIFO until being read into userspace via a read() call. Packet reception stops when a reset IOCTL is sent.

Calling CC1101::new or CC1101::set_rx_config with an RXConfig causes the driver to begin packet reception.

CC1101::receive can then later be used to read out the contents of the driver packet receive FIFO.

CC1101::reset is used to stop packet reception by the driver.

Transmit

Transmission of packets is a synchronous process.

TX occurs when an IOCTL is sent to the character device with a transmit configuration and a write() call made with the bytes to transmit. When a write() occurs, RX is paused, the device is reconfigured for TX and the provided packet is transmitted. Once TX completes, the receive config is restored and RX continues. The write() call blocks until completion of the transmission.

CC1101::transmit is used to transmit packets using a TXConfig. This call will block until TX is complete.

Device Sharing

It is possible to share a CC1101 character device between multiple receiving and transmitting process.

For example, this allows a long-running receiving process to share a device with a process that occasionally transmits.

The receiving process periodically polls the character device to check for new packets. Another process can acquire the character device while the receving process is sleeping and request a transmit. This will cause the driver to reconfigure the hardware, transmit, then return to the receive configuration and continue listening for new packets.

This behaviour is controlled by the blocking argument to CC1101::new. Specifying false will release the file handle to the character device after every CC1101::receive and CC1101::transmit call. This enables another process to aquire a handle to use the radio between events. The open() call on the character device will block until the radio becomes available again.

Specifying true will hold the file handle open while the CC1101 struct is kept in scope. This prevents another process from using the device between events.

Note - sharing a device between two receiving processes will cause packet loss, as the driver’s internal packet buffer is reset each time a new receive configuration is set.

Implementations

impl CC1101

pub fn new(
    device: &str,
    rx_config: Option<RXConfig>,
    blocking: bool
) -> Result<CC1101, CC1101Error>

Create a new handle to a CC1101 device

Providing an rx_config will configure the driver for RX with the provided configuration and begin packet reception. Received packets can be read using CC1101::receive.

blocking determines if the file handle to the device should be kept open. This prevents another process from using the radio (and reconfiguring it), but prevents sharing of the device with another process.

Example

let rx_config = RXConfig::new(433.92, Modulation::OOK, 1.0, 64, None, None, None, None, None, None, None)?;
let cc1101 = CC1101::new("/dev/cc1101.0.0", Some(rx_config), false)?;

pub fn get_rssi(&self) -> Result<u8, CC1101Error>

Get the current RSSI value from the radio

pub fn get_max_packet_size(&self) -> Result<u32, CC1101Error>

Get the maximum packet size configured in the driver

pub fn receive(&self) -> Result<Vec<Vec<u8>>, CC1101Error>

Receive packets from the radio

This will read the content of the driver’s received packet buffer if the driver is already in RX.

If the driver is not in RX (i.e CC1101::reset has been called), calling this will configure the driver for RX and begin packet reception.

Individual packets are a Vec<u8> of the size specified in the packet_length argument to RXConfig::new.

The return type is Vec<Vec<u8>>, as multiple packets can be returned in one receive call. This will be empty if no packets have been received.

Example

let rx_config = RXConfig::new(433.92, Modulation::OOK, 1.0, 64, None, None, None, None, None, None, None)?;
let cc1101 = CC1101::new("/dev/cc1101.0.0", Some(rx_config), false)?;

loop {
    let packets = cc1101.receive()?;
    for packet in packets {
        println!("Received - {:x?}", packet);
    }
    thread::sleep(time::Duration::from_millis(100));
}

pub fn transmit(
    &self,
    tx_config: &TXConfig,
    data: &[u8]
) -> Result<(), CC1101Error>

Transmit a packet via the radio using the provided configuration

Example

const PACKET: [u8; 11] = [0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f, 0x0f];       

let tx_config = TXConfig::new(433.92, Modulation::OOK, 1.0, 0.1, None, None)?;
let cc1101 = CC1101::new("/dev/cc1101.0.0", None, false)?;

cc1101.transmit(&tx_config, &PACKET)?;

pub fn reset(&mut self) -> Result<(), CC1101Error>

Issue a reset command to the device.

This will clear the received packet buffer and stop receiving. Packet reception can be resumed by calling CC1101::receive.

pub fn set_rx_config(&mut self, rx_config: &RXConfig) -> Result<(), CC1101Error>

Set the receive configuration.

This will configure the driver for RX with the provided configuration and begin packet reception. Received packets can be read using CC1101::receive.

pub fn get_rx_config(&self) -> &Option<RXConfig>

Get the configured receive config

pub fn get_device_tx_config(&mut self) -> Result<TXConfig, CC1101Error>

Get the transmit configuration currently set in the driver

pub fn get_device_rx_config(&mut self) -> Result<RXConfig, CC1101Error>

Get the receive configuration currently set in the driver

In non-blocking mode, this may differ from the value returned by CC1101::get_rx_config if another process has reconfigured the device.

pub fn get_device_registers(
    &self,
    registers_type: RegistersType
) -> Result<Registers, CC1101Error>

Get the set of hardware registers for RX/TX currently configured in the driver, or currently configured on the CC1101