Quick Start Guide

Signalyzer dongles are capable of supporting multiple serial protocols and prior of being able to communicate the Signalyzer must be configured for given operating mode.

Below is a complete example of signalyzer.script that configures Signalyzer's Port 1 for I2C operation and performs read and write operations over I2C bus.

<?xml version="1.0" encoding="utf-8"?>
<doc type="signalyzer-script" version="1.0">
  
  <!-- comments are standard xml comments -->
  <!--comment example-->
  
  <!-- import class-->
  <import filename="i2c.xml"/>
  
  <!-- configure a port -->
  <port name="my_i2c" type="i2c" map="1"/>

  <!-- one byte i2c write operation -->
  <write port="my_i2c" slave_address="94" address="93" data="0" />
  
  <!-- multibyte i2c write operation -->
  <write port="my_i2c" slave_address="94" address="99" data="[1, 0x9A, 0x33]" />
  
  <!-- one byte i2c write operation -->
  <read port="my_i2c" slave_address="0x5E" address="0x5D" bytes_to_read="1" />

  <!-- multibyte i2c read operation -->
  <read port="my_i2c" slave_address="0x5E" address="0x62" bytes_to_read="5" />
</doc>

Let's examine this example line by line.


Heading

<?xml version="1.0" encoding="utf-8"?>

This is a XML heading which should be present in any valid XML and since signalyzer.script utilizes XML syntax the heading must also be present.


Top level element

<doc type="signalyzer-script" version="1.0">

</doc>
This defines top level element of signalyzer.script and is used to identify the type and version of XML object. All signalyzer.script commands must contain inside the <doc></doc> element.


Comments

  <!-- comments are standard xml comments -->
  <!--comment example-->

These are standard XML comments. Everything between <!– and –> is considered a comments and will not be processed by signalyzer.script.


Import directive

<import filename="i2c.xml"/>

The signalyzer.script inherits many features of Object-Oriented Languages but this is outside of the scope of this Quick Start manual. Please refer to complete signalyzer.script programmer's guide for details of <import /> element. For the context of Quick Start guide, will include i2c.xml module to give signalyzer.script the ability to process I2C specific commands.


Port definition

<port name="my_i2c" type="i2c" map="1"/>
The <port /> element is used to instruct signalyzer.script to configure a given Signalyzer port for specific model of operation. Some models of Signalyzer product line have only one port, some models can have multiple ports. The name attribute defines a name for given port that will be used by the script to address the port. The map attribute maps port of Signalyzer device to given port name. The type attribute specifies the operating mode given port shall operate.


Write and Read Operations

The signalyzer.script language defines three primary operation types: write, read, write_read. The I2C protocol does not support simultaneous write and read operation therefore write_read operation will not be covered in Quick Start Guide. Please refer to complete Programmer's guide for further details.

The above example performs single byte followed by a multi byte operation, next single byte read operation is performed followed by a multi byte read operation. Each operation required number of parameters to be passed. The write and read operations in I2C mode expect following mandatory parameters to be passed:

  • port - The port name of the port where command is to be sent. The name of the port must match the name defined in <port /> element.
  • slave_address - This is the Slave Address value of device connected to I2C bus. TODO: define whether SlaveAddress must be shifted left once
  • address - This is the I2C Address value.
  • data - Data to be written onto I2C bus.
  • bytes_to_read - Number of bytes to read from device connected to I2C bus.

<write port="my_i2c" slave_address="94" address="93" data="0" />

This is the example of single byte write operation.

<write port="my_i2c" slave_address="94" address="99" data="[1, 0x9A, 0x33]" />

The array of bytes can be passed to write operation as well. The array must contain comma separated values enclosed with []. Please note: the signalyzer.script can accept values in Decimal format (i.e. 0, 5, 100), Hexadecimal (i.e. 0x10, 0xFF) or Binary representation (i.e. 0b0011, 0b10101010)

<read port="my_i2c" slave_address="0x5E" address="0x5D" bytes_to_read="1" />

<read port="my_i2c" slave_address="0x5E" address="0x62" bytes_to_read="5" />

For read operation bytes_to_read parameter specifies how many bytes shall be read. The read operation will read specified number of bytes and store read values. The topics covering how process or display read values are outside of the scope of this tutorial, please refer to complete Programmer's guide for further details.