SX10509: Server

This section provides details of how you exchange data and commands between a SPLat controller and a server, via the SX10509. This page provides an overview of the process, while subsequent pages provide more specific details.

The SX10509 SPLat Call Home module is able to perform either GET or POST requests under control of the SPLat program in your controller.

The simplest method of configuring the server URL is to enter the server domain, port and script path in the Server Configuration tab.

Data is sent to and from a server, via the SX10509, at the Xwire address which is set via "Network Address" in the Xwire Configuration tab. This is 64 by default.

Both the Xwire network transmit and receive data blocks may be between 3 and 32 bytes long. Use the longest you can afford for each, based on the amount of spare RAM you have.

The length of your transmit data block is automatically detected by the SX10509, but the length of your receive buffer must be entered on the Xwire Configuration tab. By default, this is set to 32 bytes.

To get some data from the SPLat controller to the server, you first have to send it to the SX10509 board, and then command the SX10509 to send it to the server (usually with a GET or POST request). To get some data from the server you have to command the SX10509 to request it from the server (usually with a GET or POST request), and then read the resulting data out of the SX10509.

Transferring data from the SPLat controller to the SX10509

The basic steps for sending something to the SX10509 board via Xwire are:

  1. Load a text string of length 0 to 30 bytes (or less if you have allocated less than 32 bytes to the Xwire network transmit data block) into the Xwire network transmit data block, starting at byte 2. This is the data.
  2. Set byte 1 (the 2nd byte) of the block to the number of bytes in that string.
  3. Set byte 0 of the block (the TxCommand byte) to the command that tells the SX10509 what to do with the string. It is important that the command byte is set last.
  4. Wait for the command byte to be echoed in the first byte of the Xwire network receive data block (the RAM area that is designated for data from the SX10509's network address)

The SX10509 will process a command only when the command byte in byte 0 of the network transmit block is different to the last/previously processed command. You force the SX10509 to process several commands of the same type by toggling bit 7 of the command byte. The SPLat program should always wait for the echo (the identical command byte) to appear in byte 0 of the network receive block before moving on to a subsequent command. If the command involves sending something to the server, which could be the other side of the world, this could take some time.

The SX10509 contains a 256 byte RAM buffer for holding data that is to be sent to the server. Because the Xwire link between the SPLat controller and the SX10509 can only transfer a maximum of 30 bytes at a time, you may need to load up the server transmit buffer in several Xwire transfers. Each Write command appends its data to the buffer, except a Write of zero bytes, which clears the buffer.

Transferring data from the SPLat controller to the server (via the SX10509)

The basic steps for sending some data to the server are:

  1. Clear the server transmit buffer by writing an empty (zero length) string to it, using the steps above with a Write command
  2. For each item of data you want to send to the server print it to the Xwire network transmit block, using (typically) iiPrintText and iifPrintWFW instructions, along with appropriate field delimiters, and then send it to the SX10509's server transmit buffer with a Write command.
  3. Once you have transferred all you want to send to the server (up to the 256 byte limit), send the SX10509 a command to send the data to the server. This can be either via a GET or a POST (two of the ways a web browser sends a user's data to a server).
  4. Wait for the DoGET or DoPOST command to be echoed in byte 0 of the network receive data block in the SPLat.
  5. The second byte (byte 1) will now contain the count of how many bytes of data the server responded with (which are saved inside the SX10509 for later Read). Bytes 2-5 will contain the server's response code as a floating point number. These are the codes you sometimes see on your browser, like 404 - Page Not Found.
  6. Once you have a response code, and it is OK (no errors) you can extract any data/commands that have been returned by the server, using the byte count in byte 1 of the GET/POST command echo and Read command(s).

Transferring data from the SX10509 to the SPLat controller

The basic steps for extracting server data back from the SX10509 to the controller are:

  1. Do a GET or POST. This is what triggers the server to send some data. The server cannot initiate a transfer.
  2. Get the byte count from byte 1 (2nd byte) of the GET/POST command echo (above).
  3. Extract and process the data. The Read command to the SX10509 contains a parameter that specifies a cumulative offset into the SX10509's server receive buffer (where data from the server is held). The cumulative offsets let you access different parts of the buffer. Each time you send a Read command, the SX10509 will write the requested data to the Xwire network receive block and echo the Read command. The details of how you utilise the data in the receive block will depend on how the data is formatted by the server. You will generally need instructions like iifGetNum, which converts an ASCII numeric string such as "3.1415" to a floating point number in W, and iiGetHex.

Hint: When designing the server script, it is much safer and easier to use ASCII number representation than pure binary numbers.

The identity of the server that the SX10509 will communicate with is stored in the SX10509. This information can be configured into the SX10509 during system setup. It can also be changed dynamically via Network commands. Once you understand how to send and receive data, changing the server configuration programmatically will be simple.