14.1.1 Enhanced Protocol

The Enhanced Protocol makes it possible to send commands to, and receive responses from, the scanhead.

Commands are 16 bits wide, and consist of command-code in the high byte, and an optional parameter in the low byte.

Responses are 16 or 20 bits wide, depending on the commands used to elicit them.

The Enhanced Protocol Namespace

The RAYLASE.SPICE3.ScannerEnhancedProtocol namespace provides convenient access to symbolic constants that can be used with:

Note that these symbolic constants are pre-defined with the necessary frame alignment.

You can use the symbolic constants when defining the Command-Parameter field(s) for TransceiveEnhanced, etc.

For this purpose, the Command-Parameter pair should be defined by simply adding the appropriate constants together:

Using the Enhanced Protocol namespace:

Copy

uint command =
    (uint)RAYLASE.SPICE3.ScannerEnhancedProtocol.CommandCode.SetDataSource +
    (uint)RAYLASE.SPICE3.ScannerEnhancedProtocol.DataSource.CurrentVelocity;

Alternatively, the corresponding numeric constants can be used directly:

Using Enhanced Protocol Numeric Constants:

Copy

uint command = 0x05000 + 0x00060; // achieves exactly the same as the symbolic example.

Using the Enhanced Protocol

The API provides TransceiveEnhanced for use when a response from the scanhead is expected or required, and TransmitEnhanced for cases where no response is needed.

Transceiving using the Enhanced Protocol:

Copy

// Define a couple of aliases for the sake of brevity:
using CommandCode = RAYLASE.SPICE3.ScannerEnhancedProtocol.CommandCode;
using DataSource = RAYLASE.SPICE3.ScannerEnhancedProtocol.DataSource;



        using ( ClientAPI client = new ClientAPI( CardIP ) )
        {
            client.System.ResetToDefaults();

            int timeoutMs = 500;
            uint[] commands = new uint[]
            {
                (uint)CommandCode.SetDataSource + (uint)DataSource.StatusWord,
                (uint)CommandCode.SetDataSource + (uint)DataSource.ServoBoardTemperature
            };

            int head = 0;
            try
            {
                uint[] responses =
                client.ScannerCommunication.TransceiveEnhanced( head, Axes.XY, commands, timeoutMs );

                // Extract the 16-bit values from the raw response data...
                ushort statusX = (ushort)( responses[0] >> 4 );
                ushort temperatureY = (ushort)( responses[1] >> 4 );

                Console.Out.WriteLine( $"Status (X-Axis)={statusX}, Temperature (Y-Axis)={temperatureY}" );
            }
            catch ( TimeoutException e )
            {
                Console.WriteLine( $"Timed out waiting for a response. {e}" );
            }
        }

Transmission Frame Alignment

For the Enhanced Protocol, all commands and responses are transported between the scanhead and the SP-ICE-3 Card as left-aligned payloads within 20-bit Transmission Frames.

Note
The symbolic constants for command codes and command parameters in the RAYLASE.SPICE3.ScannerEnhancedProtocol namespace are pre-defined with the necessary alignment!

Response payloads are left-aligned within the 20-bit frame, and should be handled by application programs as follows:

Response Payload	Usage
16-bit non-position data	right-shift the raw value by 4 bits
16-bit position data	right-shift the raw value by 4 bits
20-bit position data	use the value as-is

SP-ICE-3 Transmission Frame

Legacy Analog XY-ScanHeads and the Enhanced Protocol

Legacy analog XY-ScanHeads such as SS2-E, MS, MS-2, etc., use a Transmission Frame format that is not fully compatible with the Enhanced Protocol.

Attempts to use the Enhanced Protocol API methods with such scanheads will generally result in Exceptions being thrown to the calling application program.