Struct rn2903::Rn2903

pub struct Rn2903 { /* fields omitted */ }

A handle to a serial link connected to a RN2903 module.

This library guarantees safety regardless of the state of the RN2903. Refer to the documentation for sections and individual associated functions for specifics.

Examples

Basic functionality can be obtained just by using ::new_at() and ::transact(). For instance, blinking the LoStik's LED:

let mut txvr = Rn2903::new_at("/dev/ttyUSB0")
    .expect("Could not open device. Error");
loop {
    txvr.transact(b"radio set pindig GPIO10 0").unwrap();
    thread::sleep(Duration::from_millis(1000));
    txvr.transact(b"radio set pindig GPIO10 1").unwrap();
    thread::sleep(Duration::from_millis(1000));
}

Methods

impl Rn2903

Meta (type) Functions

These functions deal with the type Rn2903, providing ways to create and manipulate the structure itself.

Creating an Rn2903

There are several ways to create a Rn2903 wrapper for an RN2903 serial connection. ::new_at() is the recommended method, but ::new() can be useful if the platform does not support named serial ports, or some extra configuration is needed.

pub fn new_at<S: AsRef<OsStr>>(port_name: S) -> Result<Self>

Opens a new connection to a module at the given path or port name, with the default (and usually correct) settings from serial_config.

Example

Connecting to a module accessible over the USB0 TTY.

let txvr = Rn2903::new_at("/dev/ttyUSB0")
    .expect("Could not open device. Error");

pub fn new(port: Box<dyn SerialPort>) -> Result<Self>

Open a new connection to a module over the connection described by the given SerialPort trait object.

pub fn new_unchecked(port: Box<dyn SerialPort>) -> Self

Open a new connection to a module over the connection described by the given SerialPort trait object without performing a sys get ver check.

The results of operations on a Rn2903 struct that does not represent an actual connection to an RN2903 module are completely unpredictable, and may result in lots of badness (though not memory unsafety).

pub fn port(&mut self) -> &mut dyn SerialPort

Acquires temporary direct access to the captured SerialPort trait object.

Use this access to, for example, reconfigure the connection on the fly, or set flags that will be used by devices this crate is unaware of.

Example

Raising and then lowering the RTS signal, for example to signal a bus observer to switch on.

txvr.port().write_request_to_send(true)
    .expect("Could not set RTS. Error");
thread::sleep(Duration::from_millis(25));
txvr.port().write_request_to_send(false)
    .expect("Could not set RTS. Error");

impl Rn2903

Low-level Communications

pub fn transact(&mut self, command: &[u8]) -> Result<Vec<u8>>

Writes the specified command to the module and returns a single line in response.

This function adds the CRLF to the given command and returns the response without the CRLF.

This is the preferred low-level communication method, since the RN2903 is supposed to respond with a single line to every command.

pub fn send_line(&mut self, line: &[u8]) -> Result<()>

Writes the specified command to the module, adding a CRLF and flushing the buffer.

Using ::transact() is preferred.

pub fn read_line(&mut self) -> Result<Vec<u8>>

Reads bytes from the device until a CRLF is encountered, then returns the bytes read, not including the CRLF.

Using ::transact() is preferred.

impl Rn2903

System API Functions

pub fn system_version(&mut self) -> Result<String>

Queries the module for its firmware version information.

Returns a String like RN2903 1.0.3 Aug 8 2017 15:11:09

pub fn system_version_bytes(&mut self) -> Result<Vec<u8>>

Queries the module for its firmware version information.

As ::system_version(), but returns bytes.

pub fn system_module_reset(&mut self) -> Result<Vec<u8>>

Resets the CPU on the connected module. State in memory is lost and the MAC starts up upon reboot, automatically loading default LoRaWAN settings.

Returns the system version, like ::system_version_bytes().

pub fn system_factory_reset(&mut self) -> Result<Vec<u8>>

Performs a factory reset on the connected module. All EEPROM values are restored to factory defaults. All LoRaWAN settings set by the user are lost.

Returns the system version, like ::system_version_bytes().

pub fn system_set_nvm(&mut self, address: NvmAddress, value: u8) -> Result<()>

Set the value of the on-MCU nonvolatile memory at the given address to the given value.

pub fn system_get_nvm(&mut self, address: NvmAddress) -> Result<u8>

Get the value of the on-MCU nonvolatile memory at the given address.

impl Rn2903

Radio API Functions

pub fn radio_set_modulation_mode(&mut self, mode: ModulationMode) -> Result<()>

Set the modulation mode used by the radio for transmission and reception.

pub fn radio_rx(&mut self, timeout: u16) -> Result<Option<Vec<u8>>>

Open the receiver for the given timeout in symbols (for LoRa) or milliseconds (for FSK), returning Ok(Some(_)) if a valid packet is received or Ok(None) if no packet is received before the timeout.

impl Rn2903

MAC API Functions

pub fn mac_pause(&mut self) -> Result<u32>

Pauses the LoRaWAN MAC functionality on the device, returning the number of milliseconds for which the MAC can remain paused without affecting LoRaWAN functionality.

This command can fail with CannotPause, meaning the device is operating in a mode (like LoRaWAN Class C mode) in which pausing the MAC for any period of time would result in degraded service.

pub fn mac_resume(&mut self) -> Result<()>

Resumes LoRaWAN MAC functionality on the device after being paused.