gotelem/xbee/api_frame.go
saji 3c1a96c8e0
All checks were successful
Go / build (1.21) (push) Successful in 1m18s
Go / build (1.22) (push) Successful in 1m16s
format
2024-03-07 06:18:49 -06:00

145 lines
5.1 KiB
Go

package xbee
import (
"bytes"
"encoding/binary"
"errors"
"io"
)
// Frameable is an object that can be sent in an XBee Frame. An XBee Frame
// consists of a start delimiter, length, the payload, and a checksum.
type Frameable interface {
// returns the API identifier for this frame.
// encodes this frame correctly.
Bytes() []byte
}
// calculateChecksum is a helper function to calculate the 1-byte checksum of a data range.
// the data range does not include the start delimiter, or the length uint16 (only the frame payload)
func calculateChecksum(data []byte) byte {
var sum byte
for _, v := range data {
sum += v
}
return 0xFF - sum
}
// writeXBeeFrame takes some bytes and wraps it in an XBee frame.
//
// An XBee frame has a start delimiter, followed by the length of the payload,
// then the payload itself, and finally a checksum.
func writeXBeeFrame(w io.Writer, data []byte) (n int, err error) {
frame := make([]byte, len(data)+4)
frame[0] = 0x7E
binary.BigEndian.PutUint16(frame[1:], uint16(len(data)))
copy(frame[3:], data)
chk := calculateChecksum(data)
frame[len(frame)-1] = chk
return w.Write(frame)
}
// now we can describe frames in other files that implement Frameable.
// the remaining challenge is reception and actual API frames.
// xbee uses the first byte of the "frame data" as the API identifier or command.
//go:generate stringer -output=api_frame_cmd.go -type xbeeCmd
// XBeeCmd is the frame command type.
type XBeeCmd byte
const (
// commands sent to the xbee s3b
ATCmdType XBeeCmd = 0x08 // AT Command
ATCmdQueueType XBeeCmd = 0x09 // AT Command - Queue Parameter Value
TxReqType XBeeCmd = 0x10 // TX Request
TxReqExplType XBeeCmd = 0x11 // Explicit TX Request
RemoteCmdReqType XBeeCmd = 0x17 // Remote Command Request
// commands recieved from the xbee
ATCmdResponseType XBeeCmd = 0x88 // AT Command Response
ModemStatusType XBeeCmd = 0x8A // Modem Status
TxStatusType XBeeCmd = 0x8B // Transmit Status
RouteInfoType XBeeCmd = 0x8D // Route information packet
AddrUpdateType XBeeCmd = 0x8E // Aggregate Addressing Update
RxPktType XBeeCmd = 0x90 // RX Indicator (AO=0)
RxPktExplType XBeeCmd = 0x91 // Explicit RX Indicator (AO=1)
IOSampleType XBeeCmd = 0x92 // Data Sample RX Indicator
NodeIdType XBeeCmd = 0x95 // Note Identification Indicator
RemoteCmdRespType XBeeCmd = 0x97 // Remote Command Response
)
// Now we will implement receiving packets from a character stream.
// we first need to make a thing that produces frames from a stream using a scanner.
// xbeeFrameSplit is a split function for bufio.scanner. It makes it easier to handle the FSM
// for extracting data from a stream. For the Xbee, this means that we must
// find the magic start character, (check that it's escaped), read the length,
// and then ensure we have enough length to finish the token, requesting more data
// if we do not.
//
// see https://pkg.go.dev/bufio#SplitFunc for more info
// https://medium.com/golangspec/in-depth-introduction-to-bufio-scanner-in-golang-55483bb689b4
func xbeeFrameSplit(data []byte, atEOF bool) (advance int, token []byte, err error) {
if atEOF && len(data) == 0 {
// there's no data, request more.
return 0, nil, nil
}
if startIdx := bytes.IndexByte(data, 0x7E); startIdx >= 0 {
// we have a start character. see if we can get the length.
// we add 4 since start delimiter (1) + length (2) + checksum (1).
// the length inside the packet represents the frame data only.
if len(data[startIdx:]) < 3 {
// since we don't have enough bytes to get the length, instead we
// will discard all data before the start index
return startIdx, nil, nil
}
// FIXME: add bounds checking! this can panic.
var frameLen = int(binary.BigEndian.Uint16(data[startIdx+1:startIdx+3])) + 4
// if the value of frameLen is > 0x100, we know that it's screwed up.
// this helps keep error duration lowered.
if frameLen > 0x100 {
return startIdx + 1, nil, nil
}
if len(data[startIdx:]) < frameLen {
// we got the length, but there's not enough data for the frame. we can trim the
// data that came before the start, but not return a token.
return startIdx, nil, nil
}
// there is enough data to pull a frame, so return it.
// todo: is startDix + frameLen + 1?
return startIdx + frameLen, data[startIdx : startIdx+frameLen], nil
}
// we didn't find a start character in our data, so request more. trash everythign given to us
return len(data), nil, nil
}
// parseFrame takes a framed packet and returns the contents after checking the
// checksum and start delimiter.
func parseFrame(frame []byte) ([]byte, error) {
if frame[0] != 0x7E {
return nil, errors.New("incorrect start delimiter")
}
fsize := len(frame)
if calculateChecksum(frame[3:fsize-1]) != frame[fsize-1] {
return nil, errors.New("checksum mismatch")
}
return frame[3 : fsize-1], nil
}
// stackup
// low level readwriter (serial or IP socket)
// XBee library layer (frame encoding/decoding to/from structs)
// AT command layer (for setup/control)
// xbee conn-like layer (ReadWriter + custom control functions)
// application marshalling format (msgpack or json or gob)
// application