aboutsummaryrefslogtreecommitdiff
path: root/xbee/xbee.h
diff options
context:
space:
mode:
Diffstat (limited to 'xbee/xbee.h')
-rw-r--r--xbee/xbee.h261
1 files changed, 261 insertions, 0 deletions
diff --git a/xbee/xbee.h b/xbee/xbee.h
new file mode 100644
index 0000000..a40487e
--- /dev/null
+++ b/xbee/xbee.h
@@ -0,0 +1,261 @@
+/*
+ * xbee.h:
+ * Maxstream XBee module Interface Header
+ *
+ * (c) 2006-2008 Tymm Twillman <tymm@booyaka.com>
+ *
+ *
+ * NOTE: This doesn't touch hardware; it's up to developers to link in functions
+ * that handle hardware communication.
+ *
+ * DEVELOPERS: Pieces you need to implement (see prototypes, below):
+ * xbee_alloc_pkt_mem (can just return static data)
+ * xbee_free_pkt_mem (can do nothing if not dynamic)
+ *
+ * xbee_out
+ * xbee_recv_pkt
+ *
+ * What you need to call from wherever you read data from UART, etc:
+ * xbee_in
+ *
+ * Incoming data from UART, etc. should be passed to xbee_in; it will
+ * be built into well-formed packets and passed to xbee_recv_pkt
+ * for further processing.
+ *
+ * Outgoing data will be passed to xbee_out to be passed off to
+ * the XBee hardware.
+ *
+ *
+ */
+
+#ifndef XBEE_H
+#define XBEE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdint.h>
+#include <errno.h>
+
+/*----------------------------------------------------------------------------
+ Definitions for commands the XBee recognizes
+ ----------------------------------------------------------------------------*/
+
+/* Basic communication parameters/values */
+
+#define XBEE_CMD_CHANNEL "CH"
+#define XBEE_CMD_PAN_ID "ID"
+#define XBEE_CMD_DEST_ADDR64_HI "DH"
+#define XBEE_CMD_DEST_ADDR64_LO "DL"
+#define XBEE_CMD_SRC_ADDR16 "MY"
+#define XBEE_CMD_SER_HI "SH"
+#define XBEE_CMD_SER_LO "SL"
+#define XBEE_CMD_RAND_DLY_SLOTS "RN"
+#define XBEE_CMD_MAC_MODE "MM"
+#define XBEE_CMD_COORD_ENA "CE"
+#define XBEE_CMD_SCAN "SC"
+#define XBEE_CMD_SCAN_DURATION "SD"
+#define XBEE_CMD_ASSOC_END "A1"
+#define XBEE_CMD_ASSOC_COORD "A2"
+#define XBEE_CMD_ASSOC_STATUS "AI"
+#define XBEE_CMD_RSSI "DB"
+
+/* Transceiver Control */
+
+#define XBEE_CMD_PWR_LEVEL "PL"
+#define XBEE_CMD_CCA_THRESH "CA"
+
+/* Sleep Parameters */
+
+#define XBEE_CMD_SLEEP_MODE "SM"
+#define XBEE_CMD_SLEEP_TIMEOUT "ST"
+#define XBEE_CMD_SLEEP_PERIOD "SP"
+#define XBEE_CMD_SLEEP_PERIOD_DISASSOC "DP"
+
+/* Interface parameters */
+
+#define XBEE_CMD_DATA_RATE "BD"
+#define XBEE_CMD_PACKETIZATION_TIMEOUT "RO"
+#define XBEE_CMD_DIO7_CONFIG "D7"
+#define XBEE_CMD_DIO6_CONFIG "D6"
+#define XBEE_CMD_DIO5_CONFIG "D5"
+#define XBEE_CMD_PWM0_CONFIG "PO"
+#define XBEE_CMD_API_ENA "AP"
+#define XBEE_CMD_PULLUP_ENA "PR"
+
+/* Version Info */
+
+#define XBEE_CMD_VERS_FIRMWARE "VR"
+#define XBEE_CMD_VERS_HARDWARE "HV"
+#define XBEE_CMD_VERS_FIRM_VERBOSE "VL"
+
+/* Received Signal Strength */
+
+#define XBEE_CMD_RSSI_PWM_TIMER "RP"
+#define XBEE_CMD_RSS "DB"
+
+/* Error counters */
+
+#define XBEE_CMD_CCA_FAILS "EC"
+#define XBEE_CMD_ACK_FAILS "EA"
+
+/* AT Command Params */
+
+#define XBEE_CMD_AT_MODE_TIMEOUT "CT"
+#define XBEE_CMD_AT_GUARD_TIME "GT"
+#define XBEE_CMD_AT_CMD_CHAR "CC"
+#define XBEE_CMD_AT_EXIT "CN"
+
+/* XBEE specific routing */
+
+#define XBEE_CMD_NODE_FIND_DEST "DN"
+#define XBEE_CMD_NODE_DISCOVER "ND"
+#define XBEE_CMD_NODE_ID "NI"
+#define XBEE_CMD_ACTIVE_SCAN "AS"
+#define XBEE_CMD_FORCE_DISASSOC "DA"
+#define XBEE_CMD_ENERGY_SCAN "ED"
+#define XBEE_CMD_FORCE_POLL "FP"
+
+/* Misc */
+
+#define XBEE_CMD_WRITE_PARAMS "WR"
+#define XBEE_CMD_RESET_SOFT "FR"
+#define XBEE_CMD_APPLY_CHANGES "AC"
+#define XBEE_CMD_RESTORE_DEFAULTS "RE"
+
+
+/*----------------------------------------------------------------------------
+ Structures usefull for communicating with the XBee in API mode
+ ----------------------------------------------------------------------------*/
+
+/* Packets are wrapped with a start & length */
+typedef struct {
+ uint8_t start; /* 0x7e */
+ uint16_t len;
+} __attribute__ ((__packed__)) xbee_pkt_hdr_t;
+
+
+/* Packets can be broken up into headers, a packet type, a number of data
+ * bytes and a crc (at the end of the data)
+ */
+typedef struct {
+ xbee_pkt_hdr_t hdr;
+ uint8_t type;
+ uint8_t data[0];
+ /* uint8_t crc; */
+} __attribute__ ((__packed__)) xbee_pkt_t;
+
+
+/* Context for tracking current state of communication with an
+ * XBee module
+ */
+typedef struct {
+ struct {
+ uint8_t bytes_left;
+ uint8_t bytes_rcvd;
+ xbee_pkt_t *packet;
+ uint8_t hdr_data[sizeof(xbee_pkt_hdr_t)];
+ } in;
+ struct {
+ uint8_t frame_id;
+ } out;
+ void *user_context; // yours to pass data around with
+} __attribute__ ((__packed__)) xbee_t;
+
+/* This is used for keeping track of your data as things get passed around
+ * through the xbee interface
+ */
+#define xbee_user_context(xbee) ((xbee).user_context)
+
+/*----------------------------------------------------------------------------
+ Internal calls
+ ----------------------------------------------------------------------------*/
+
+/* Calculate CRC on an xbee packet */
+uint8_t xbee_crc(const xbee_pkt_t *pkt);
+
+
+/*----------------------------------------------------------------------------
+ Generally all the functions you need to call
+ ----------------------------------------------------------------------------*/
+
+/* Receive data, calling xbee_recv_pkt on each packet when it's done
+ * assembling; this should be called with raw data from UART, etc.
+ * as it comes in. *** YOU NEED TO CALL THIS ***
+ */
+void xbee_in(xbee_t *xbee, const void *data, uint8_t len);
+
+/* Send a packet with a 64-bit destination address (Series 1) */
+int xbee_send64(xbee_t *xbee,
+ const void *data,
+ uint8_t len,
+ uint8_t opt,
+ const uint8_t addr[8]);
+
+/* Send a packet with a 16-bit destination address (Series 1) */
+int xbee_send16(xbee_t *xbee,
+ const void *data,
+ uint8_t len,
+ uint8_t opt,
+ const uint8_t addr[2]);
+
+/* Send a command to the xbee modem */
+int xbee_send_at_cmd(xbee_t *xbee,
+ const char cmd[],
+ uint8_t param_len,
+ const uint8_t *params);
+
+/* Send a command to a remote xbee modem (Series 2 & Newer Series 1 only) */
+int xbee_send_remote_at_cmd(xbee_t *xbee,
+ const char cmd[],
+ uint8_t param_len,
+ uint8_t apply,
+ const uint8_t params[],
+ const uint8_t addr64[8],
+ const uint8_t addr16[2]);
+
+/* Initialize the XBee interface */
+void xbee_init(xbee_t *xbee);
+
+/*----------------------------------------------------------------------------
+ MUST be provided externally to this package
+ ----------------------------------------------------------------------------*/
+
+/* Queue a packet for transmission (needs to queue packet to be sent to XBEE
+ * module; e.g. copy the packet to a UART buffer).
+ * On error, -1 should be returned and the packet should NOT be freed.
+ * On success, 0 should be returned; if XBEE_ALLOC is set, this function or
+ * someone downstream is responsible for freeing it -- the packet has been
+ * handed off. This is to minimize copying of data.
+ */
+int xbee_out(xbee_t *xbee, xbee_pkt_t *pkt, uint8_t len);
+
+/* Handle an incoming packet; the packet will be fully formed and verified
+ * for proper construction before being passed off to this function. This
+ * function should dig into the packet & process based on its contents.
+ */
+int xbee_recv_pkt(xbee_t *xbee, xbee_pkt_t *pkt, uint8_t len);
+
+
+/*----------------------------------------------------------------------------
+ Must be provided externally only if using dynamic memory (which allows more
+ than one packet to be queued at a time)
+ ----------------------------------------------------------------------------*/
+
+/* Return a buffer for an xbee packet; at least <len> bytes need to be allocated
+ *
+ * Direction since we may want to have different allocations mechanisms/etc
+ * for xmit vs recv.
+ */
+void *xbee_alloc_pkt_mem(uint8_t direction, uint8_t len);
+
+/* Free up an allocated packet */
+void xbee_free_pkt_mem(xbee_pkt_t *pkt);
+
+
+#ifdef __cplusplus
+};
+#endif
+
+#endif /* #ifndef XBEE_H ... */