.. _tutorials:
.. highlight:: console

Tutorials
=========

Note: If you have multiple gateways, all commands can also take a ``--gateway`` option to specify which one. For brevity, that option is omitted from the below examples.


How to communicate with peripherals on the I2C bus with lager CLI
-----------------------------------------------------------------

Intro
#####

In order to debug hardware designs with chips that utilize an I2C bus, it's often handy to have a way of communicating with the bus directly. The Lager Gateway has a built-in I2C peripheral that you can use to communicate with your I2C chips or microcontrollers. 

Setup
#####

Install the latest version of the `lager-cli` tool, and confirm that you are able to communicate with your Lager Gateway.

Sending Bytes
#############

`lager-cli` includes a `i2c write` command for transmitting bytes via I2C. This command has a mandatory `device` argument, which is the I2C address of the device you're writing to (in either `0x` hex or integer notation), as well as one or more bytes of data to transmit. An optional `--reg` argument can be provided with the address of the register to send the bytes to. The datatype of the provided bytes can be set with the `--type` argument. 

.. code-block:: bash

    # Write 0xFFFF to device 0x12 (18)
    > lager i2c write --type hex 0x12 0xFF 0xFF

    # Write 0x12 0x34 to device 0x12 (18) register 0x10 (16)
    > lager i2c write --type hex --reg 0x10 0x12 0x34

    # Write "hello" to device 0x12 (18)
    > lager i2c write --type string 18 test


Requesting Bytes
################

`lager-cli` also includes a `i2c read` command for requesting bytes from a specific I2C address. A `--length` argument can be used to set the number of bytes to request, otherwise one byte will be requested.

.. code-block:: bash

    # Read 1 byte from device 0x12 (18)
    > lager i2c read 0x12
    
    # Read 2 bytes from device 0x12 (18) register 0x10 (16) in hex format
    > lager i2c read --length 2 --type hex --reg 16 0x12
    
    # Read a 5-byte string from device 0x12 (18)
    > lager i2c read --length 5 --type string 0x12


--------------------------------


How to communicate with peripherals on the SPI bus with lager CLI
-----------------------------------------------------------------

Intro
#####

In order to debug hardware designs with chips that utilize an SPI bus, it's often handy to have a way of communicating with the bus directly. The Lager Gateway has a built-in SPI peripheral that you can use to communicate with your SPI chips or microcontrollers. 

Setup
#####

Install the latest version of the `lager-cli` tool, and confirm that you are able to communicate with your Lager Gateway.

SPI Modes
#########

To change the SPI mode (see https://en.wikipedia.org/wiki/Serial_Peripheral_Interface), use the `--mode` argument.

Chip Selects
############

Currently only one hardware chip select pin works. TODO fix this.

Reading Bytes
#############

`lager-cli` includes an `spi read` command for reading bytes from an SPI peripheral. It accepts a mandatory `length` argument which determines how many bytes to read.

.. code-block:: bash

    # Read 4 bytes using mode 0 (the default)
    > lager spi read 4
    
    # Read a 5-byte string from SPI using mode 1
    > lager spi read --mode 1 --type string 5
    
    # Read 3 integer bytes from SPI at 500 KHz
    > lager spi read --speed 500000 --type int


Writing Bytes
#############

`lager-cli` includes an `spi write` command for writing bytes to an SPI peripheral. It accepts an arbitrary number of bytes to send.

.. code-block:: bash

    # Write 4 bytes using mode 0 (the default)
    > lager spi write 0x12 0x34 0x56 0x78
    
    # Write the string "hello" using mode 3 at 500 Khz
    > lager spi write --mode 3 --speed 500000 hello
    
    # Write 3 integers
    > lager spi write 0 127 255


Transferring Bytes
##################

`lager-cli` includes an `spi transfer` command that accepts an arbitrary number of bytes to send to an SPI peripheral, and returns the bytes that were simultaneously received.

.. code-block:: bash

    # Write the string "hello" and return the received bytes
    > lager spi transfer --type string hello
    Lager SPI Received 5 bytes: world


--------------------------------


Stream serial output from a DUT
-------------------------------

1. List your serial ports: ``lager gateway serial-ports``.
::

    ➜  ~ lager gateway serial-ports
    /dev/ttyS0 - Lager Gateway serial port
    /dev/ttyACM0 - SEGGER VL805 USB 3.0 Host Controller; serial number 123456789
    /dev/ttyUSB1 - Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC; serial number FT1ABCDE

2. Use the serial port device name with ``lager uart`` to stream output from that serial port and save it to a file: ``lager uart --serial-port /dev/ttyACM0 | tee serial.log``. This will stream the output to your console and save it to a file called ``serial.log``. See the :ref:`UART command reference<uart>` for the full set of options available to ``lager uart``.
::

    ➜  ~ lager uart --serial-port /dev/ttyACM0 | tee serial.log
    test_mpu9250_drv.c:44:test_who_am_i_read:FAIL: Expected 113 Was 0
    test_mpu9250_drv.c:62:test_sample_rate_divider:FAIL: Expected 1 Was 0
    test_mpu9250_drv.c:79:test_enabling_disabling_fifo_modes:FAIL: Expected 1 Was 0
    test_mpu9250_drv.c:98:test_gyro_fs_select:FAIL: Expected 1 Was 0
    test_mpu9250_drv.c:36:test_42:PASS
    test_mpu9250_drv.c:37:test_blinky:PASS

    -----------------------
    6 Tests 4 Failures 0 Ignored