rn2483

package module
v0.0.0-...-3ae95b5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 28, 2021 License: MIT Imports: 12 Imported by: 5

README

rn2483 Go Reference build status

Go library for interfacing with RN2483 and RN2903 LoRa modules via their serial interface, particularly LoStik USB devices.

Feature Completeness

  • Building blocks for implementing commands:
    • rn2483.(Device).Sendf for sending commands
    • rn2483.(Device).ReadResponse for reading responses
    • rn2483.CheckCommandResponse for validating common command responses
    • rn2483.(Device).ExecuteCommand as a common building block for commands
    • rn2483.(Device).ExecuteCommandChecked and rn2483.(Device).ExecuteCommandCheckedStrict as a common building block for simple commands with easily validated responses
  • All sys commands
    • purposely excludes sys eraseFW as it seemed too dangerous to make convenient, easy to implement manually using the building blocks provided above
  • mac commands have only been implemented where they facilitate accessing the radio commands:
    • mac pause
  • Basic radio commands have been implemented
    • radio tx and radio rx
    • generic radio set <x> <y> and radio get <x> commands
    • radio set pwr
  • Simple fake implementation for local development and automated testing

Todo

  • Add implementations for more commands

References

Alternatives

  • https://github.com/sagneessens/RN2483 - a more fully featured library, but is implemented using a global singleton restricting you to one device per application, depends on a specific serial port implementation, and has limited error handling/reporting.

Documentation

Index

Constants

View Source 
const (
	// UserNVMStart is the address of the first byte in user NVM that can be addressed
	UserNVMStart uint16 = 0x300
	// UserNVMEnd is the last address in user NVM that can be addressed
	UserNVMEnd uint16 = 0x3FF
)

Variables

View Source 
var (
	ErrInvalidParam    = errors.New("invalid parameter")
	ErrUnknown         = errors.New("unknown error")
	ErrTransceiverBusy = errors.New("the transceiver is currently busy")
)
View Source 
var (
	ErrReceiveTimeout = errors.New("reception unsuccessful, timeout occurred")

	ContinuousReceiveMode uint16 = 0
)
View Source 
var AllPins = []PinName{
	PinGPIO00,
	PinGPIO01,
	PinGPIO02,
	PinGPIO03,
	PinGPIO04,
	PinGPIO05,
	PinGPIO06,
	PinGPIO07,
	PinGPIO08,
	PinGPIO09,
	PinGPIO10,
	PinGPIO11,
	PinGPIO12,
	PinGPIO13,
	PinGPIO14,
	PinUARTCTS,
	PinUARTRTS,
	PinTEST0,
	PinTEST1,
}

AllPins lists all the GPIO pins that can be asserted

View Source 
var (
	ErrTransmitTimeout = errors.New("transmission unsuccessful, interrupted by radio WDT")
)
View Source 
var (
	// FirmwareVersionRegex is a regex for breaking down a version string reported by the device
	FirmwareVersionRegex = regexp.MustCompile("^(.+)\\s+([0-9]+\\.[0-9]+\\.[0-9]+)\\s+(.+)$")
)
View Source 
var KnownDeviceSKUs = []DeviceSKU{DeviceRN2483, DeviceRN2903}

KnownDeviceSKUs is a list of all known device SKUs

View Source 
var KnownRadioParameters = []string{
	"bt", "mod", "freq", "pwr", "sf", "afcbw", "rxbw", "bitrate",
	"fdev", "prlen", "crc", "iqi", "cr", "wdt", "bw", "snr",
}

KnownRadioParameters lists the known parameters that can be get/set with radio commands

View Source 
var (
	// UserNVMLength is the number of bytes of user NVM that can be addressed
	UserNVMLength = (UserNVMEnd + 1) - UserNVMStart
)

Functions

func ByteToHex 

func ByteToHex(b byte) string

ByteToHex returns the hex representation of a single byte

func BytesToHex 

func BytesToHex(b []byte) string

BytesToHex returns the hex representation of a byte array

func CheckCommandResponse 

func CheckCommandResponse(line string, allowUnknown bool) error

CheckCommandResponse validates a command response against known error codes, optionally failing unknown responses

func HexToByte 

func HexToByte(h string) (byte, error)

HexToByte decodes a hex string into a single byte

func HexToBytes 

func HexToBytes(h string) ([]byte, error)

HexToBytes decodes a hex string into a byte array

func HexToUInt16 

func HexToUInt16(h string) (uint16, error)

HexToUInt16 decodes a hex string of a big-endian uint16

func PadHex 

func PadHex(h string, digits int) string

PadHex pads a hexadecimal string with leading 0s until it satisfied the desired number of digits

func PadHexToEvenLength 

func PadHexToEvenLength(h string) string

PadHexToEvenLength pads a hex string with a single leading 0 only if the input hex string is an odd length

func ReadNVM 

func ReadNVM(d *Device, start, amount uint16) ([]byte, error)

ReadNVM reads a block of data from user NVM

func UInt16ToHex 

func UInt16ToHex(v uint16) string

UInt16ToHex returns the big-endian hex representation of a uint16

func WriteNVM 

func WriteNVM(d *Device, address uint16, data []byte) error

WriteNVM writes a block of data to user NVM

Types

type Config 

type Config struct {
	Serial io.ReadWriteCloser
}

Config allows for configuring a new Device

type DebugSerial 

type DebugSerial struct {
	Serial io.ReadWriteCloser
	Logger logr.Logger

	// AssumeText controls whether data flowing through this device is likely printable text, if true then
	// logged data will be printed as text, otherwise it is treated as unprintable binary and is displayed
	// however the logging library chooses to render []byte (often base64)
	AssumeText bool
}

DebugSerial wraps a serial device and logs data flowing to/from that device

func (*DebugSerial) Close 

func (d *DebugSerial) Close() error

Close implements the io.ReadWriteCloser interface by calling the underlying Serial implementation

func (*DebugSerial) Read 

func (d *DebugSerial) Read(p []byte) (n int, err error)

Read implements the io.ReadWriteCloser interface by calling the underlying Serial implementation and logging the read data

func (*DebugSerial) Write 

func (d *DebugSerial) Write(p []byte) (n int, err error)

Write implements the io.ReadWriteCloser interface by calling the underlying Serial implementation and logging the sent data

type Device 

type Device struct {
	// contains filtered or unexported fields
}

Device represents a single RN2483 (or 2903) device, providing methods for configuring and querying its state and invoking the various features of the device (primarily transmitting & receiving packets)

func New 

func New(cfg Config) *Device

New creates a new Device

func (*Device) Close 

func (d *Device) Close() error

Close shuts the underlying serial device

func (*Device) ExecuteCommand 

func (d *Device) ExecuteCommand(format string, a ...interface{}) (string, error)

ExecuteCommand sends the provided command, then reads and returns the response

func (*Device) ExecuteCommandChecked 

func (d *Device) ExecuteCommandChecked(format string, a ...interface{}) (string, error)

ExecuteCommandChecked sends the provided command, reads the response, checks it for common error codes, then returns the response

func (*Device) ExecuteCommandCheckedStrict 

func (d *Device) ExecuteCommandCheckedStrict(format string, a ...interface{}) error

ExecuteCommandCheckedStrict sends the provided command, reads the response and then checks it is one of a set of known command responses, failing any unrecognised responses

func (*Device) FactoryReset 

func (d *Device) FactoryReset() (*FirmwareVersion, error)

FactoryReset resets the device to its factory configuration

func (*Device) GetHWEUI 

func (d *Device) GetHWEUI() (string, error)

GetHWEUI gets the device's preprogrammed EUI node address as a hex string

func (*Device) GetRadioParameter 

func (d *Device) GetRadioParameter(name string) (string, error)

GetRadioParameter gets the specified radio parameter as a raw string value (direct from the response message)

func (*Device) GetRadioPower 

func (d *Device) GetRadioPower() (int, error)

GetRadioPower gets the radio's current configured transmit power

func (*Device) GetVDD 

func (d *Device) GetVDD() (Voltage, error)

GetVDD retrieves the current VDD voltage measured by the device

func (*Device) GetVersion 

func (d *Device) GetVersion() (*FirmwareVersion, error)

GetVersion retrieves the device's version information

func (*Device) PauseMAC 

func (d *Device) PauseMAC() (time.Duration, error)

PauseMAC pauses the LoRaWAN stack to allow transceiver configuration.

func (*Device) RadioRx 

func (d *Device) RadioRx(windowSize uint16) ([]byte, error)

RadioRx causes the device to listen for, and return, a single packet. The window size determines how long it will listen for, behaving differently depending on the current radio configuration (particularly modulation mode).

func (*Device) RadioTx 

func (d *Device) RadioTx(data []byte) error

RadioTx attempts to transmit a packet of data using the radio's current configuration

func (*Device) ReadNVM 

func (d *Device) ReadNVM(address uint16) (byte, error)

ReadNVM reads a single byte of data from user NVM

func (*Device) ReadResponse 

func (d *Device) ReadResponse() (string, error)

ReadResponse allows for easily reading a line of text from the device in response to a command

func (*Device) Reset 

func (d *Device) Reset() (*FirmwareVersion, error)

Reset resets the device, reverting to its stored configuration

func (*Device) Sendf 

func (d *Device) Sendf(format string, a ...interface{}) error

Sendf allows for easily sending arbitrary commands to the device

func (*Device) SetDigitalGPIO 

func (d *Device) SetDigitalGPIO(gpio PinName, value bool) error

SetDigitalGPIO sets the specified GPIO pin to on or off

func (*Device) SetRadioParameter 

func (d *Device) SetRadioParameter(name string, value interface{}) error

SetRadioParameter sets the specified radio parameter to the given value

func (*Device) SetRadioPower 

func (d *Device) SetRadioPower(power int) error

SetRadioPower sets the radio's transmit power

func (*Device) Sleep 

func (d *Device) Sleep(duration time.Duration) error

Sleep causes the device to sleep for the specified duration

func (*Device) WriteNVM 

func (d *Device) WriteNVM(address uint16, value byte) error

WriteNVM writes a single byte of data to user NVM

type DeviceSKU 

type DeviceSKU string

DeviceSKU identifies a device model 

const (
	DeviceRN2483 DeviceSKU = "RN2483"
	DeviceRN2903 DeviceSKU = "RN2903"
)

type FirmwareVersion 

type FirmwareVersion struct {
	// Raw contains the original version string
	Raw string

	// SKU indicates the device model
	SKU DeviceSKU

	// Major is the first component of the firmware version number
	Major int
	// Minor is the second component of the firmware version number
	Minor int
	// Revision is the third component of the firmware version number
	Revision int

	// ReleaseTime is the time at which this firmware version was released
	ReleaseTime time.Time
}

FirmwareVersion contains the result of parsing a version string returned by several sys commands

func ParseFirmwareVersion 

func ParseFirmwareVersion(s string) (*FirmwareVersion, error)

ParseFirmwareVersion attempts to parse a version string reported by the device

func (*FirmwareVersion) IsKnownSKU 

func (fw *FirmwareVersion) IsKnownSKU() bool

IsKnownSKU compares this firmware version's reported SKU to the list of known SKUs

func (*FirmwareVersion) VersionString 

func (fw *FirmwareVersion) VersionString() string

VersionString combines the major, minor and revision components into a single string for easier printing

type PinName 

type PinName string

PinName identifies the GPIO pin that may be asserted 

const (
	PinGPIO00  PinName = "GPIO00"
	PinGPIO01  PinName = "GPIO01"
	PinGPIO02  PinName = "GPIO02"
	PinGPIO03  PinName = "GPIO03"
	PinGPIO04  PinName = "GPIO04"
	PinGPIO05  PinName = "GPIO05"
	PinGPIO06  PinName = "GPIO06"
	PinGPIO07  PinName = "GPIO07"
	PinGPIO08  PinName = "GPIO08"
	PinGPIO09  PinName = "GPIO09"
	PinGPIO10  PinName = "GPIO10"
	PinGPIO11  PinName = "GPIO11"
	PinGPIO12  PinName = "GPIO12"
	PinGPIO13  PinName = "GPIO13"
	PinGPIO14  PinName = "GPIO14"
	PinUARTCTS PinName = "UART_CTS"
	PinUARTRTS PinName = "UART_RTS"
	PinTEST0   PinName = "TEST0"
	PinTEST1   PinName = "TEST1"
)

type Voltage 

type Voltage uint16

Voltage represents a voltage measured by the device

func (Voltage) Millivolts 

func (v Voltage) Millivolts() uint16

Millivolts is the measured voltage in Millivolts (mV) as an integer

func (Voltage) Volts 

func (v Voltage) Volts() float64

Volts is the measured voltage in Volts (V) as a decimal value

Source Files

View all Source files

Directories

Path Synopsis
examples module
ether

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.