nora
/
rn2903
1
0
Fork 0
Code Issues Pull Requests Releases Activity

Compare commits

base: nora:36bdf9dd16e19bb4a4349689d34e6995f4fafd73
Branches Tags
nora:main
..
compare: nora:6943fffe26891cd65fcc2d88ebff77f913f52df2
Branches Tags
nora:main

No commits in common. "36bdf9dd16e19bb4a4349689d34e6995f4fafd73" and "6943fffe26891cd65fcc2d88ebff77f913f52df2" have entirely different histories.
36bdf9dd16 ... 6943fffe26

6 changed files with 29 additions and 188 deletions
Show Stats Expand all files Collapse all files

22
CHANGELOG.md
View File

@ -5,28 +5,8 @@ All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## Unreleased - v0.2.0
## [Unreleased]
### Added
- `Rn2903::system_version_bytes()`
- `Rn2903::system_factory_reset()`
- `Rn2903::system_module_reset()`
- `Rn2903::mac_pause()` and `::mac_resume()`
- `BadResponse` and `CannotPause` error variants
- Examples directory with LED blinky and LoRa packet RX examples
### Changed
### Deprecated
### Removed
- `main.rs` (moved to an example)
### Fixed
### Security
## v0.1.0
### Added
- GNU GPL v3 license

10
CONTRIBUTING.md
View File

@ -17,13 +17,3 @@ CHANGELOG.md.
All method documentation is written in the present tense. For example, "Creates a new..."
rather than "Create a new...".
## Cutting a Release
When cutting a release:
- In CHANGELOG, rename the Unreleased section and add a new Unreleased section above it
- Make a commit with only that change
- Tag that commit like "v1.0.0"
- Push main and the tag
- `cargo publish`

32
examples/blinky.rs
View File

@ -1,32 +0,0 @@
use rn2903::Rn2903;
use std::env::args;
use std::process::exit;
use std::thread;
use std::time::Duration;
fn main() {
let args: Vec<_> = args().collect();
if args.len() <= 1 {
eprintln!("rn2903_blinky <serial port>");
eprintln!("\tReset the module and toggle pin 0b10 on and off.");
eprintln!("\tThis corresponds to the blue user LED on the LoStik.");
exit(1);
}
let mut txvr = Rn2903::new_at(&args[1]).expect("Could not open device. Error");
println!(
"Successfully connected. Version: {}",
txvr.system_version()
.expect("Could not read from device. Error:")
);
txvr.system_module_reset().unwrap();
txvr.transact(b"mac pause").unwrap();
loop {
txvr.transact(b"sys set pindig GPIO10 1").unwrap();
thread::sleep(Duration::from_millis(1000));
txvr.transact(b"sys set pindig GPIO10 0").unwrap();
thread::sleep(Duration::from_millis(1000));
}
}

32
examples/lora_packet_rx.rs
View File

@ -1,32 +0,0 @@
use rn2903::Rn2903;
use std::env::args;
use std::process::exit;
use std::thread;
use std::time::Duration;
fn main() {
let args: Vec<_> = args().collect();
if args.len() <= 1 {
eprintln!("rn2903_lora_packet_rx <serial port>");
eprintln!("\tRecieve LoRa packets and print their corresponding hex values.");
exit(1);
}
let mut txvr = Rn2903::new_at(&args[1]).expect("Could not open device. Error");
println!(
"Successfully connected. Version: {}",
txvr.system_version()
.expect("Could not read from device. Error:")
);
txvr.mac_pause().unwrap();
txvr.transact(b"sys set pindig GPIO10 0").unwrap();
txvr.transact(b"radio rx 0").unwrap();
loop {
println!("{:?}", txvr.read_line().unwrap());
txvr.transact(b"sys set pindig GPIO10 1").unwrap();
thread::sleep(Duration::from_millis(100));
txvr.transact(b"sys set pindig GPIO10 0").unwrap();
txvr.transact(b"radio rx 0").unwrap();
}
}

104
src/lib.rs
View File

@ -36,19 +36,6 @@ quick_error! {
display("Could not verify version string. Expected a RN2903 firmware revision, got '{}'",
version)
}
/// The device returned a response that doesn't make sense, given the command that
/// was issued.
BadResponse(expected: String, response: String) {
description("bad response from module")
display("Received a bad response from the module. Expected '{}', got '{}'.",
expected, response)
}
/// The device is operating in a mode which prevents MAC functionality from being
/// paused, but a pause was requested.
CannotPause {
description("the LoRaWAN MAC cannot be paused")
display("The LoRaWAN MAC cannot be paused right now, but a pause was requested.")
}
/// The program has become disconnected from the RN2903 module due to an I/O
/// error. It is possible the device was physically disconnected, or that the
/// host operating system closed the serial port for some reason.
@ -60,12 +47,6 @@ quick_error! {
}
}
impl Error {
fn bad_response<S: Into<String>, T: Into<String>>(expected: S, response: T) -> Self {
Self::BadResponse(expected.into(), response.into())
}
}
/// Universal `Result` wrapper for the RN2903 interface.
pub type Result<T> = std::result::Result<T, Error>;
@ -90,7 +71,7 @@ use std::thread;
/// # Examples
///
/// Opening a serial port with slightly modified settings. In this case, the baud rate
/// has been reduced.
/// has been reduced.
///
/// ```no_run
/// let settings = serialport::SerialPortSettings {
@ -149,10 +130,12 @@ pub struct Rn2903 {
port: Box<dyn SerialPort>,
}
/// # Meta (type) Functions
/// # Meta (type) Functions
///
/// These functions deal with the type `Rn2903`, providing ways to create and manipulate
/// the structure itself.
/// the structure itself. Aside from performing validation of the device on the other side
/// of the serial link, these functions do not communicate with the module.
///
/// ## 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
@ -163,7 +146,7 @@ impl Rn2903 {
/// [`serial_config`](fn.serial_config.html).
///
/// # Example
///
///
/// Connecting to a module accessible over the USB0 TTY.
/// ```no_run
/// # use rn2903::Rn2903;
@ -196,7 +179,7 @@ impl Rn2903 {
pub fn new_unchecked(port: Box<dyn SerialPort>) -> Self {
Self { port }
}
/// Acquires temporary direct access to the captured `SerialPort` trait object.
///
/// Use this access to, for example, reconfigure the connection on the fly,
@ -223,7 +206,7 @@ impl Rn2903 {
}
}
/// # Low-level Communications
/// # Low-level Communications
impl Rn2903 {
/// Writes the specified command to the module and returns a single line in response.
///
@ -237,21 +220,6 @@ impl Rn2903 {
self.read_line()
}
/// Convenience function for situations where only one response is expected according
/// to the module's documentation. Receiving another response means something wacky
/// is going on.
fn transact_expecting(&mut self, command: &[u8], expectation: &[u8]) -> Result<()> {
let bytes = self.transact(command)?;
if bytes != expectation {
Err(Error::bad_response(
bytes_to_string(expectation),
bytes_to_string(&bytes),
))
} else {
Ok(())
}
}
/// Writes the specified command to the module, adding a CRLF and flushing the buffer.
///
/// Using [`::transact()`](#method.transact) is preferred.
@ -260,7 +228,7 @@ impl Rn2903 {
let mut cursor = 0;
while cursor < bytes.len() {
cursor += self.port.write(&bytes[cursor..])?;
}
}
self.port.flush()?;
thread::sleep(Duration::from_millis(500));
Ok(())
@ -306,6 +274,7 @@ impl Rn2903 {
Ok(vec)
}
}
/// # System API Functions
@ -316,56 +285,5 @@ impl Rn2903 {
pub fn system_version(&mut self) -> Result<String> {
let bytes = self.transact(b"sys get ver")?;
Ok(bytes_to_string(&bytes))
}
/// Queries the module for its firmware version information.
///
/// As `::system_version()`, but returns bytes.
pub fn system_version_bytes(&mut self) -> Result<Vec<u8>> {
self.transact(b"sys get ver")
}
/// 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_module_reset(&mut self) -> Result<Vec<u8>> {
self.transact(b"sys reset")
}
/// 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_factory_reset(&mut self) -> Result<Vec<u8>> {
self.transact(b"sys factoryRESET")
}
}
/// # MAC API Functions
impl Rn2903 {
/// 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_pause(&mut self) -> Result<u32> {
let val = bytes_to_string(&self.transact(b"mac pause")?);
let ms: u32 = match val.parse() {
Ok(v) => v,
Err(_) => return Err(Error::bad_response("<integer>", val)),
};
if ms == 0 {
Err(Error::CannotPause)
} else {
Ok(ms)
}
}
/// Resumes LoRaWAN MAC functionality on the device after being paused.
pub fn mac_resume(&mut self) -> Result<()> {
self.transact_expecting(b"mac resume", b"ok")
}
}
}

17
src/main.rs Normal file
View File

@ -0,0 +1,17 @@
use rn2903::{Rn2903, bytes_to_string};
use std::thread;
use std::time::Duration;
fn main() {
let mut txvr = Rn2903::new_at("/dev/ttyUSB0").expect("Could not open device. Error");
println!(
"Successfully connected. Version: {}",
txvr
.system_version()
.expect("Could not read from device. Error:")
);
dbg!(bytes_to_string(&txvr.transact(b"sys set pindig GPIO10 1").unwrap()));
thread::sleep(Duration::from_millis(200));
dbg!(bytes_to_string(&txvr.transact(b"sys set pindig GPIO10 0").unwrap()));
}