Add XBeeWithCallbacks::waitForStatus()

This method loops until a status response is received (e.g. a
AtCommandResponse, TxResponse, etc.) to greatly simplify getting the
result of a command sent. While waiting, any other responses are
processed by the callbacks as normal, so no response gets lost while
waiting.

A matchStatus() helper method is introduced, preparing to reuse it in a
future commit.

Author: matthijskooijman

XBee.cpp

@@ -1671,3 +1671,44 @@ void XBeeWithCallbacks::loopBottom() {
 	if (!called)
 		_onOtherResponse.call(getResponse());
 }
+
+uint8_t XBeeWithCallbacks::matchStatus(uint8_t frameId) {
+	uint8_t id = getResponse().getApiId();
+	uint8_t *data = getResponse().getFrameData();
+	uint8_t len = getResponse().getFrameDataLength();
+	uint8_t offset = 0;
+
+	// Figure out if this frame has a frameId and if so, where the
+	// status byte to return is located
+	if (id == AT_COMMAND_RESPONSE)
+		offset = 3;
+	else if (id == REMOTE_AT_COMMAND_RESPONSE)
+		offset = 13;
+	else if (id == TX_STATUS_RESPONSE)
+		offset = 1;
+	else if (id == ZB_TX_STATUS_RESPONSE)
+		offset = 4;
+
+	// If this is an API frame that contains a status, the frame is
+	// long enough to contain it and the frameId matches the one
+	// given, return the status byte
+	if (offset && offset < len && data[0] == frameId)
+		return data[offset];
+	return 0xff;
+}
+
+uint8_t XBeeWithCallbacks::waitForStatus(uint8_t frameId, uint16_t timeout) {
+	unsigned long start = millis();
+	do {
+		if (loopTop()) {
+			uint8_t status = matchStatus(frameId);
+			if (status != 0xff)
+				return status;
+
+			// Call regular callbacks
+			loopBottom();
+		}
+	} while (millis() - start < timeout);
+	return XBEE_WAIT_TIMEOUT ;
+}
+

XBee.h

@@ -123,6 +123,8 @@
 #define ADDRESS_NOT_FOUND 0x24
 #define ROUTE_NOT_FOUND 0x25
 #define PAYLOAD_TOO_LARGE 0x74
+// Returned by XBeeWithCallbacks::waitForStatus on timeout
+#define XBEE_WAIT_TIMEOUT 0xff
 
 // modem status
 #define HARDWARE_RESET 0
@@ -884,7 +886,42 @@ class XBeeWithCallbacks : public XBee {
 	 * buffer is processed and the appropriate callbacks are called.
 	 */
 	void loop();
+
+	/**
+	 * Wait for a status API response with the given frameId and
+	 * return the status from the packet (for ZB_TX_STATUS_RESPONSE,
+	 * this returns just the delivery status, not the routing
+	 * status). If the timeout is reached before reading the
+	 * response, XBEE_WAIT_TIMEOUT is returned instead.
+	 *
+	 * While waiting, any other responses received are passed to the
+	 * relevant callbacks, just as if calling loop() continuously
+	 * (except for the status response sought, that one is only
+	 * passed to the OnResponse handler and no others).
+	 *
+	 * After this method returns, the response itself can still be
+	 * retrieved using getResponse() as normal.
+	 */
+	uint8_t waitForStatus(uint8_t frameId, uint16_t timeout);
 private:
+	/**
+	 * Internal version of waitFor that does not need to be
+	 * templated (to prevent duplication the implementation for
+	 * every response type you might want to wait for). Instead of
+	 * using templates, this accepts the apiId to wait for and will
+	 * cast the given response object and the argument to the given
+	 * function to the corresponding type. This means that the
+	 * void* given must match the api id!
+	 */
+	bool waitForInternal(uint8_t apiId, void *response, uint16_t timeout, void *func, uintptr_t data);
+
+	/**
+	 * Helper that checks if the current response is a status
+	 * response with the given frame id. If so, returns the status
+	 * byte from the response, otherwise returns 0xff.
+	 */
+	uint8_t matchStatus(uint8_t frameId);
+
 	/**
 	 * Top half of a typical loop(). Calls readPacket(), calls
 	 * onPacketError on error, calls onResponse when a response is