Added udp example and support for XBee 3 Cellular

Added more common methods

Author: felixgalindo

README.md

@@ -51,7 +51,7 @@ This section provides an overview of the key methods available in the XBee class
 - `XBeeInit()`: Initializes the XBee module.
 - `XBeeConnect()`: Connects the XBee module to a network.
 - `XBeeDisconnect()`: Disconnects the XBee module from the network.
-- `XBeeSendData()`: Sends data through the XBee module.
+- `XBeeSendPacket()`: Sends data through the XBee module.
 - `XBeeSoftReset()`: Performs a soft reset on the XBee module.
 - `XBeeHardReset()`: Performs a hard reset on the XBee module.
 - `XBeeProcess()`: Processes incoming and outgoing data for the XBee module.
@@ -86,7 +86,7 @@ The following methods are specific to the XBee LR (LoRaWAN) subclass and are **n
 - `XBeeLRSetAppEUI()`: Configures the Application EUI used for OTAA join.
 - `XBeeLRSetAppKey()`: Sets the AppKey for LoRaWAN OTAA authentication.
 - `XBeeLRSetNwkKey()`: Sets the Network Key used for network traffic encryption.
-- `XBeeLRSendData()`: Sends a LoRaWAN uplink packet using the LR frame interface.
+- `XBeeLRSendPacket()`: Sends a LoRaWAN uplink packet using the LR frame interface.
 
 Each of these methods provides essential functionality for managing and communicating with XBee devices within a network. Ensure that you refer to these methods when developing applications that involve XBee modules.
 
@@ -170,7 +170,7 @@ After creating the XBee LR instance, initialize the XBee LR module, configure th
 
 ### Sending Data
 
-To send data over the XBee LR network, use the `XBeeLRSendData` method. Here's an example of preparing and sending a payload:
+To send data over the XBee LR network, use the `XBeeLRSendPacket` method. Here's an example of preparing and sending a payload:
 
 ```c
 // XBeeLR payload to send
@@ -183,7 +183,7 @@ XBeeLRPacket_t packet = {
     .ack = 0,
 };
 
-if (!XBeeSendData(myXbeeLr, &packet)) {
+if (!XBeeSendPacket(myXbeeLr, &packet)) {
     printf("Failed to send data.");
 } else {
     printf("Data sent successfully.");
@@ -307,7 +307,7 @@ int main() {
         .ack = 0,
     };
 
-    if (!XBeeSendData(myXbeeLr, &packet)) {
+    if (!XBeeSendPacket(myXbeeLr, &packet)) {
         printf("Failed to send data.");
     } else {
         printf("Data sent successfully.");

examples/xbee_cellular/Makefile

@@ -20,17 +20,22 @@ CORE_SRCS = $(SRC_DIR)/xbee.c \
             $(SRC_DIR)/xbee_at_cmds.c \
             $(SRC_DIR)/xbee_cellular.c
 
-EXAMPLE_SRC = $(EXAMPLE_DIR)/xbee_cellular_http_get_example.c
-PORT_SRC    = $(PORTS_DIR)/port_$(PLATFORM).c
+PORT_SRC = $(PORTS_DIR)/port_$(PLATFORM).c
 
-OBJS = $(patsubst %.c, $(BUILD_DIR)/%.o, \
-        $(notdir $(CORE_SRCS)) $(notdir $(EXAMPLE_SRC)) $(notdir $(PORT_SRC)))
+EXAMPLE_HTTP = $(EXAMPLE_DIR)/xbee_cellular_http_get_example.c
+EXAMPLE_UDP  = $(EXAMPLE_DIR)/xbee_cellular_udp_echo_example.c
 
-# Output binary
-TARGET = $(BUILD_DIR)/xbee_cellular_http_get_example
+OBJS_HTTP = $(patsubst %.c, $(BUILD_DIR)/%.o, \
+             $(notdir $(CORE_SRCS)) $(notdir $(EXAMPLE_HTTP)) $(notdir $(PORT_SRC)))
+
+OBJS_UDP = $(patsubst %.c, $(BUILD_DIR)/%.o, \
+            $(notdir $(CORE_SRCS)) $(notdir $(EXAMPLE_UDP)) $(notdir $(PORT_SRC)))
+
+TARGET_HTTP = $(BUILD_DIR)/xbee_cellular_http_get_example
+TARGET_UDP  = $(BUILD_DIR)/xbee_cellular_udp_echo_example
 
 # Default rule
-all: $(BUILD_DIR) $(TARGET)
+all: $(BUILD_DIR) $(TARGET_HTTP) $(TARGET_UDP)
 
 # Create build directory
 $(BUILD_DIR):
@@ -47,7 +52,10 @@ $(BUILD_DIR)/%.o: $(PORTS_DIR)/%.c
 	$(CC) $(CFLAGS) -c $< -o $@
 
 # Linking
-$(TARGET): $(OBJS)
+$(TARGET_HTTP): $(OBJS_HTTP)
+	$(CC) $(CFLAGS) $^ -o $@
+
+$(TARGET_UDP): $(OBJS_UDP)
 	$(CC) $(CFLAGS) $^ -o $@
 
 clean:

examples/xbee_cellular/xbee_cellular_http_get_example.c

@@ -1,5 +1,5 @@
 /***************************************************************************//**
- * @file xbee_cellular_http_getexample.c
+ * @file xbee_cellular_http_get_example.c
  * @brief Example application demonstrating the use of the XBeeCellular driver.
  *
  * This file contains a sample application that demonstrates how to use the
@@ -56,19 +56,31 @@
 static bool responseReceived = false;
 
 /**
- * Callback triggered when data is received via SOCKET_RECEIVE frame (0xCD).
+ * @brief Callback triggered when data is received via SOCKET_RECEIVE (0xCD)
+ *        or SOCKET_RECEIVE_FROM (0xCE) frame.
  *
- * This function prints out the payload from the remote server in plain text format.
- * Typically used to handle HTTP response content received over TCP.
+ * This function prints the payload from the remote peer in plain text format.
+ * If the source IP and port are known (UDP), they are printed as well.
+ *
+ * @param[in] self Pointer to the XBee instance.
+ * @param[in] data Pointer to the XBeeCellularPacket_t payload descriptor.
  */
 void OnReceiveCallback(XBee* self, void* data) {
     (void)self;
     XBeeCellularPacket_t* packet = (XBeeCellularPacket_t*)data;
 
     responseReceived = true;
 
+    if (packet->ip[0] != 0 || packet->remotePort != 0) {
+        portDebugPrintf("Received from %u.%u.%u.%u:%u on socket %u\n",
+            packet->ip[0], packet->ip[1], packet->ip[2], packet->ip[3],
+            packet->remotePort, packet->socketId);
+    } else {
+        portDebugPrintf("Received on socket %u\n", packet->socketId);
+    }
+
     portDebugPrintf("[Payload ASCII Dump]:\n");
-    for (int i = 0; i < packet->payloadSize; i++) {
+    for (int i = 0; i < packet->payloadSize; ++i) {
         char c = packet->payload[i];
         portDebugPrintf("%c", (c >= 32 && c <= 126) ? c : '.');
     }
@@ -186,7 +198,7 @@ int main() {
     }
 
     portDebugPrintf("HTTP transaction complete. Exiting.\n");
-    XBeeCellularSocketClose((XBee*)xbee, socketId);
+    XBeeCellularSocketClose((XBee*)xbee, socketId, false);
     XBeeCellularDestroy(xbee);
     return 0;
 }

examples/xbee_cellular/xbee_cellular_udp_echo_example.c

@@ -0,0 +1,159 @@
+/***************************************************************************//**
+ *  @file xbee_cellular_udp_echo_example.c
+ *
+ *  @brief Sends a UDP datagram to Digi’s public echo server (52.43.121.77:10001)
+ *         and prints the echoed payload when it comes back.
+ *
+ *  The flow implements the Extended-Socket “UDP” example:
+ *    1)  Socket Create   (0x40, protocol 0x02)
+ *    2)  Socket Bind     (0x46, choose a local port)
+ *    3)  Socket SendTo   (0x45)                --> TX-Status (0x89)
+ *    4)  Socket ReceiveFrom (0xCE)             --> our RX callback
+ *    5)  Socket Close    (0x43)                --> Close-Resp (0xCF)
+ *
+ *  @author
+ *    Felix Galindo <felix.galindo@digi.com>
+ *  @license
+ *    MIT
+ ******************************************************************************/
+
+#include "xbee_cellular.h"
+#include "port.h"
+#include <string.h>
+#include <stdio.h>
+#include <stdbool.h>
+
+/* ---------- serial device per-platform ---------------------------------- */
+#if defined(_WIN32)
+  #define DEFAULT_SERIAL_PORT "COM3"
+#elif defined(__APPLE__)
+  #define DEFAULT_SERIAL_PORT "/dev/cu.usbserial-1110"
+#elif defined(__linux__)
+  #define DEFAULT_SERIAL_PORT "/dev/ttyUSB0"
+#else
+  #define DEFAULT_SERIAL_PORT ""
+#endif
+
+/* ---------- globals ------------------------------------------------------ */
+static volatile bool echoReceived = false;
+
+/* ---------- user callbacks ---------------------------------------------- */
+static void onReceive(XBee *self, void *frame)
+{
+    (void)self;
+    const XBeeCellularPacket_t *p = (const XBeeCellularPacket_t *)frame;
+
+    echoReceived = true;
+
+    portDebugPrintf("[UDP RX] %u bytes from %u.%u.%u.%u:%u (socket %u):\n",
+                    p->payloadSize,
+                    p->ip[0], p->ip[1], p->ip[2], p->ip[3],
+                    p->remotePort, p->socketId);
+
+    for (uint16_t i = 0; i < p->payloadSize; ++i) {
+        char c = p->payload[i];
+        portDebugPrintf("%c", (c >= 32 && c <= 126) ? c : '.');
+    }
+    portDebugPrintf("\n");
+}
+
+static void onSend(XBee *self, void *frame)
+{
+    (void)self;
+    (void)frame;
+    portDebugPrintf("[UDP TX] payload accepted for transmit\n");
+}
+
+/* ---------- main --------------------------------------------------------- */
+int main(void)
+{
+    /* Hardware abstraction table ------------------------------------------- */
+    const XBeeHTable hw = {
+        .PortUartInit  = portUartInit,
+        .PortUartRead  = portUartRead,
+        .PortUartWrite = portUartWrite,
+        .PortFlushRx   = portFlushRx,
+        .PortDelay     = portDelay,
+        .PortMillis    = portMillis
+    };
+
+    /* Callback table ------------------------------------------------------- */
+    const XBeeCTable cb = {
+        .OnReceiveCallback = onReceive,
+        .OnSendCallback    = onSend
+    };
+
+    portDebugPrintf("XBee 3 Cellular – UDP Echo example (Extended Socket)\n");
+
+    /* Instance ------------------------------------------------------------- */
+    XBeeCellular *xbee = XBeeCellularCreate(&cb, &hw);
+
+    if (!XBeeInit((XBee *)xbee, 9600, DEFAULT_SERIAL_PORT)) {
+        portDebugPrintf("[ERR] failed to open serial port\n");
+        return -1;
+    }
+
+    /* APN etc. – identical to the HTTP example ---------------------------- */
+    const XBeeCellularConfig_t cfg = {
+        .apn     = "broadband",
+        .simPin  = "",
+        .carrier = ""
+    };
+    XBeeConfigure((XBee *)xbee, &cfg);
+
+    /* Attach to network ---------------------------------------------------- */
+    portDebugPrintf("Waiting for network attach...\n");
+    XBeeConnect((XBee *)xbee, false);
+    while (!XBeeCellularConnected((XBee *)xbee)) {
+        portDelay(1000);
+        portDebugPrintf(".");
+    }
+    portDebugPrintf("\n[OK] attached!\n");
+
+    /* 1) Socket Create (protocol = UDP 0x02) ------------------------------- */
+    uint8_t sockId = 0;
+    if (!XBeeCellularSocketCreate((XBee *)xbee, XBEE_PROTOCOL_UDP, &sockId)) {
+        portDebugPrintf("[ERR] socket create failed\n");
+        return -1;
+    }
+
+    /* 2) Bind to local port 0x1234 ---------------------------------------- */
+    if (!XBeeCellularSocketBind((XBee *)xbee, sockId, 0x1234, true)) {
+        portDebugPrintf("[ERR] bind failed\n");
+        return -1;
+    }
+    portDebugPrintf("[OK] socket %u bound to local port 0x1234\n", sockId);
+
+    /* 3) SendTo Digi echo server ------------------------------------------ */
+    const uint8_t ip[4] = { 52, 43, 121, 77 };
+    const uint8_t payload[] = "echo this";
+
+    if (!XBeeCellularSocketSendTo((XBee *)xbee,
+                                  sockId,
+                                  ip,
+                                  10001,
+                                  payload,
+                                  sizeof(payload) - 1))
+    {
+        portDebugPrintf("[ERR] sendto failed\n");
+        return -1;
+    }
+    portDebugPrintf("[OK] UDP datagram sent, waiting for echo...\n");
+
+    /* 4) Wait (≤10 s) for echo --------------------------------------------- */
+    uint32_t t0 = portMillis();
+    while (!echoReceived && (portMillis() - t0) < 10000) {
+        XBeeProcess((XBee *)xbee);
+        portDelay(100);
+    }
+
+    if (!echoReceived)
+        portDebugPrintf("[WARN] timed-out waiting for echo\n");
+
+    /* 5) Close socket ------------------------------------------------------ */
+    XBeeCellularSocketClose((XBee *)xbee, sockId, false);
+
+    XBeeCellularDestroy(xbee);
+    portDebugPrintf("Done.\n");
+    return 0;
+}

examples/xbee_lr/xbee_lr_example.c

@@ -168,7 +168,7 @@ int main() {
                     portDebugPrintf("%02X", examplePayload[i]);
                 }
                 portDebugPrintf("\n");
-                if (XBeeSendData((XBee*)myXbeeLr, &packet)) {
+                if (XBeeSendPacket((XBee*)myXbeeLr, &packet)) {
                     printf("Failed to send data.\n");
                 } else {
                     printf("Data sent successfully.\n");

include/xbee.h

@@ -134,7 +134,7 @@ struct XBee {
 bool XBeeInit(XBee* self, uint32_t baudrate, void* device);
 bool XBeeConnect(XBee* self, bool blocking);
 bool XBeeDisconnect(XBee* self);
-uint8_t XBeeSendData(XBee* self, const void*);
+uint8_t XBeeSendPacket(XBee* self, const void*);
 bool XBeeSoftReset(XBee* self);
 void XBeeHardReset(XBee* self);
 void XBeeProcess(XBee* self);
@@ -144,6 +144,13 @@ bool XBeeApplyChanges(XBee* self);
 bool XBeeSetAPIOptions(XBee* self, const uint8_t value);
 bool XBeeGetFirmwareVersion(XBee* self, uint32_t* version);
 bool XBeeConfigure(XBee* self, const void* config);
+bool XBeeFactoryReset        (XBee* self);                          /* ATFR */
+bool XBeeExitCommandMode     (XBee* self);                          /* ATCN */
+bool XBeeSetApiEnable        (XBee* self, uint8_t mode);            /* ATAP */
+bool XBeeSetBaudRate         (XBee* self, uint8_t rateCode);        /* ATBD */
+bool XBeeGetLastRssi         (XBee* self, int8_t*  rssiOut);        /* ATDB */
+bool XBeeGetHardwareVersion  (XBee* self, uint16_t* hvOut);         /* ATHV */
+bool XBeeGetSerialNumber     (XBee* self, uint64_t* snOut);         /* ATSH/ATSL */
 
 #if defined(__cplusplus)
 }

include/xbee_api_frames.h

@@ -232,12 +232,17 @@
      XBEE_API_TYPE_CELLULAR_SOCKET_CONNECT = 0x42,  ///< Frame to connect a socket
      XBEE_API_TYPE_CELLULAR_SOCKET_CLOSE = 0x43,    ///< Frame to close a socket
      XBEE_API_TYPE_CELLULAR_SOCKET_SEND = 0x44,     ///< Frame to send socket data
+     XBEE_API_TYPE_CELLULAR_SOCKET_SEND_TO = 0x45,  ///< Frame to send UDP data to a specific address
+     XBEE_API_TYPE_CELLULAR_SOCKET_BIND = 0x46,     ///< Frame to bind a socket to a local port
      XBEE_API_TYPE_CELLULAR_SOCKET_CREATE_RESPONSE = 0xC0, ///< Response to socket create
      XBEE_API_TYPE_CELLULAR_SOCKET_OPTION_RESPONSE = 0xC1, ///< Response to socket option
      XBEE_API_TYPE_CELLULAR_SOCKET_CONNECT_RESPONSE = 0xC2, ///< Response to socket connect
+     XBEE_API_TYPE_CELLULAR_SOCKET_CLOSE_RESPONSE = 0xC3, ///< Response to socket close
+     XBEE_API_TYPE_CELLULAR_SOCKET_BIND_RESPONSE = 0xC6, ///< Response to socket bind
+
      XBEE_API_TYPE_CELLULAR_SOCKET_RX = 0xCD,       ///< Frame for receiving data
      XBEE_API_TYPE_CELLULAR_SOCKET_RX_FROM = 0xCE,  ///< Frame for receiving UDP data with source
-    XBEE_API_TYPE_CELLULAR_SOCKET_STATUS = 0xCF, ///< Frame for socket status
+     XBEE_API_TYPE_CELLULAR_SOCKET_STATUS = 0xCF, ///< Frame for socket status
 
      /**< XBee GPIO/ADC Related API Frames */
      XBEE_API_TYPE_IO_DATA_SAMPLE_RX = 0x92,        ///< Frame for receiving IO data samples (GPIO/ADC)

include/xbee_at_cmds.h

@@ -60,7 +60,8 @@ typedef enum {
     AT_AP,   /**< API Enable */
     AT_BD,   /**< Baud Rate */
     AT_WR,   /**< Write to non-volatile memory */
-    AT_RE,   /**< Restore factory defaults */
+    AT_RE,   /**< Soft Reset */
+    AT_FR,   /**< Factory Reset */
     AT_VR,   /**< Firmware Version */
     AT_AC,   /**< Apply Changes */
     AT_NR,   /**< Network Reset */
@@ -114,7 +115,7 @@ typedef enum {
     AT_JV,   /**< Channel Verification */
     AT_LD,   /**< Node Discovery Time */
     AT_AO,   /**< API Options */
-
+    AT_HV,   /**< Hardware Version */
     //@todo: move xbee familiar specific commands to their own file
 
     /**< XBee 3 RF Specific AT Commands */