send_serial command definition

The send_serial command sends serial data to a specific XBee node in your network. To use this command, add it to an SCI request inside the RCI do_command element.

Command syntax

The send_serial command must follow this syntax:

<send_serial addr=”{address|broadcast}”                  encoding={“base64”|”utf-8”}”>value</send_serial>

Command attributes

• addr
  • Usage: Required.

  • Description: This attribute indicates the destination address of the node to which the content indicated by the command body should be transmitted.

  • Value: Legal values for this attribute include:

    The 64-bit IEEE address of the node following one of these patterns:

    XX:XX:XX:XX:XX:XX:XX:XX

    [XX:XX:XX:XX:XX:XX:XX:XX]!

    XXXXXXXXXXXXXXXX

    XX-XX-XX-XX-XX-XX-XX-XX

    The string broadcast, which transmits the string to all nodes using a broadcast packet.

• encoding
  • Usage: Optional.

  • Description: Specifies how the character data in the command elements is processed.

  • Value: The following encoding types are allowed:
    • base64: Use Base64 encoding. Character data is decoded during command processing prior to transmit on the RF network.
    • utf-8: Use UTF-8 variable-width encoding. While you can specify this encoding type, current limitations in RCI/SCI processing through Remote Manager mean that true UTF-8 encoding is not passed cleanly through all systems and end-to-end. It is only safe to use ASCII. Specifying 'utf-8' is primarily useful for evaluation only.
    • Default value: base64.

Command body (value)

The command body contains the data to be transmitted to the specified XBee node of the network. The command body content depends on the value of the encoding attribute:

• base64: The command body value must be encoded in base64. The XBee Industrial Gateway Python application will receive the encoded content but, prior to transmission to the corresponding XBee node, the application will decode the command body to its original content and that will be transmitted.
• utf-8: The command body value must be the serial data that you want to send to the XBee node. The entire content of the command body as received by the gateway Python application will be transmitted subject to whitespace handling rules of XML and the limitations of Remote Manager to represent individual code points. For best results, base64 encoding is preferred for production code and evaluation is best when limited to the ASCII subset.

Note Whitespace is not significant when the XBee Industrial Gateway Python application processes base64. However, whitespace in UTF-8 is significant, because it is impossible to determine whether the whitespace should be considered as such and thus take the conservative approach of keeping it significant and passing it on.

Request and reply examples

• Request

  This SCI request sends a serial data command with the text Hello, World! encoded in base64 to the XBee node of our network corresponding to the MAC address 00:11:22:33:44:55:65:77.

  Note The request is using a dummy device ID and XBee MAC address. You will need to use your own XBee Industrial Gateway device ID and XBee MAC address if you want to test this example.

  <sci_request version="1.0">
    <send_message>
      <targets>
          <device id="00000000-00000000-001122FF-FF334455"/>
      </targets>
  <rci_request version="1.1">
      <do_command target="xbgw">
            <send_serial addr="00:11:22:33:44:55:66:77"
                      encoding="base64"> SGVsbG8sIFdvcmxkIQ==
            </send_serial>
      </do_command>
    </rci_request>
   </send_message>
  </sci_request>

• Reply

  If the SCI request succeeds, you will receive a SCI reply containing the send_serial command response element. As it was successful, the response will be empty.

  <sci_reply version="1.0">
    <send_message>
        <device id="00000000-00000000-001122FF-FF334455">
            <rci_reply version="1.1">
                <do_command target="xbgw">
                    <responses command="send_serial">
                        <response/>
                   </responses>
                </do_command>
            </rci_reply>
        </device>
     </send_message>
  </sci_reply>
  

  If the SCI request fails, you will receive an SCI reply containing the send_serial command response element that includes an error element indicating the cause of the error. For example:

  <sci_reply version="1.0">
      <send_message>
          <device id="00000000-00000000-001122FF-FF334455">    
              <rci_reply version="1.1">
                  <do_command target="xbgw">
                      <responses command="send_serial">
                         <response>
                            <error id="encoding">
                                <desc>Unrecognized encoding</desc>
                                <hint>basd64</hint>
                            </error>
                    </response>
                 </responses>
              </do_command>
           </rci_reply>
         </device>
      </send_message>
  </sci_reply>

The error element contains an id attribute indicating the error identifier. For more information regarding the possible XBee Industrial Gateway Python application error identifiers, see XBee Industrial Gateway Python application command errors.

The desc element displays the meaning of the error identifier, and the hint element provides an explanation of what caused the received error.