Host GAP CLI

Warning

The development of the host GAP CLI is still in progress. Some features may not work yet. For the same reason, there is no example yet, only a test is available if you want to do some tests, and/or get familiar with it.

The host GAP CLI provides a graphical interface to send commands easily to the GAP CLI runtime code, that aims to handle some pre-configured commands, such as flashing or SSBL related stuff for instance. See the GAP CLI Protocol for more details.

It runs on a host, usually a computer, and is connected to GAP through UART. Using it requires a USB-UART converter then.

In addition of all the features described below, host GAP CLI can also be used to print GAP’s logs. See Console IO for more details.

Usage

Hardware setup

UART flow control is optional. Make the useful connections depending on it, between a GAP UART interface and the USB-UART converter. Connect the other part of the converter to an USB port of your PC, or any other host you may use.

Default UART pads in example is:

UART0:: #define PAD_UART_RX ( PI_PAD_067 ) // CN2 Pin 6 #define PAD_UART_TX ( PI_PAD_041 ) // CN3 Pin 8 #define PAD_UART_RTS ( PI_PAD_042 ) // CN4 Pin 10 #define PAD_UART_CTS ( PI_PAD_034 ) // CN2 Pin 4
UART1: #define PAD_UART_RX ( PI_PAD_044 ) // MIKROE RX #define PAD_UART_TX ( PI_PAD_045 ) // MIKROE TX #define PAD_UART_RTS ( PI_PAD_040 ) // MIKROE SDA #define PAD_UART_CTS ( PI_PAD_034 ) // MIKROE CS

If you want to use other pads, please change the pad configs in utils/gap_cli/include/uart_cli_phy.h

Launching software

As mentioned in the presentation, the host GAP CLI is running on an host, and a runtime GAP CLI code is executed on GAP.

Setup

Please open two terminals, and source and build the SDK on both of them, with the option WITH_GUI_TOOLS=1. Please check the Getting Started section if any question how to do so.

Launching the runtime GAP CLI on GAP

Note

Source files are in the ~/gap_sdk/utils/gap_cli/ folder for the GAP CLI feature, and there is a tests folder for tests. Please go in this tests folder.

Note

Please find the default configuration in the sdk.config file. You can change it if needed, depending your hardware setup and needs. You can change it through the CMake menuconfig target too.

In the second terminal, (on the tests folder) run the following commands:

cmake -B build
cmake --build build -t run

Launching the host GAP CLI on host

Note

Source files are in ~/gap_sdk/utils/host_gap_cli/clisender/ folder.

On the SDK top level folder, run the following commands:

cmake --build build -t install # Create and install the executable
clisender                      # Launch the application

cmake --build build -t install # Create and install the executable
clisender --gvsoc              # Launch the application

cmake --build build -t install
clisender [--gvsoc] [--port <port>] [--fc] [--bps <bps>] [--secure <psk_id>] --comand <command> [<command_arguments>]

--gvsoc: Run on GVSoC
--port <port>: Port for the connection with GAP
- On board: something like ttyUSB0 (default)
- On GVSoC: same integer as the one given in your runtime (default 25000)
--fc: Enable UART flow control
--bps <bps>: Set UART baud rate
--secure <psk_id>: Encrypts channel. <psk_id> is the ID of the pre-shared key to use.

--command <command>: The command to run

Get the status of GAP CLI
--command status
Flash a binary file on given flash
--command flasher <flash> <file> <offset>
<flash>: The flash where to flash the file. Only mram for now

<file>: Absolute path of the file to flash

<offset>: Offset in the flash
Update a partition with the SSBL. Open and close are automatically done
--command ssbl <flash> <layout> [<full_update> <encrypted> <key_id>]
<flash>: The flash where to update the partition. Only mram for now

<layout>: Absolute path of the layout of the partition we want to have

<full_update>: Is it a full update (1) or not (0). Full update cleans all partitions related to the current running app before doing the update.

<encrypted>: Should the CLI encrypt the payload ? Yes (1) / No (0)

<key_id>: ID of the key to use for encryption if <encrypted> is 1
Load a key into the secret storage
--command load_key <key_file> <key_id>
<key_file>: Absolute path of the binary file containing the key

<key_id>: ID of the key
Enable JATG on GAP
--command jtag
Set some power parameters
--command power <type> <arguments>
<type>: The parameter type to set
Set domains’ frequency
--command power frequencies <periph> <fc> <cluster> <sfu>
<periph>: Frequency of the PERIPH domain in Hertz

<fc>: Frequency of the FC domain in Hertz

<cluster>: Frequency of the CLUSTER domain in Hertz

<sfu>: Frequency of the SFU domain in Hertz
Set GAP’s voltage alimentation
--command power voltage <vdd>
<vdd>: Voltage value of VDD in mV
Warning

You may need to be careful if you increase the frequencies or decrease the voltage. Some frequencies require a minimal voltage supply to be available.
Put GAP into sleep and set wake up source
--command sleep <mode> <wakeup> [<wakeup_arguments>]
<mode>: Sleep mode

deep: Deep sleep

retentive: Retentive sleep

light: Light sleep

<wakeup>: Wake up source
Wake up from RTC
--command sleep <mode> rtc <div> <countdown>
<div>: Clock divider

<countdown>: Countdown
Wake up from GPIO
--command sleep <mode> gpio <gpio> <level>
<gpio>: GPIO number. See the SLEEP_GPIO_CTRL register for more informations

<gpio>

GAP’s GPIO

0

GPIO42

1

GPIO43

2

GPIO65

3

GPIO66

4

GPIO67

5

GPIO68

6

GPIO89

7

GPIO88

8

GPIO40

9

GPIO41

10

GPIO34

11

GPIO35

12

GPIO36

13

GPIO37

14

GPIO39

15

GPIO38

<level>: Level of the GPIO that will trigger the wake up

low: Trigger wake up on low level

high: Trigger wake up on high level
Wake up from UART
--command sleep <mode> uart
To wake up GAP from this wake up mode, use the following command:
--command wakeup
Note

If you are on board and you use Cutecom to see UART transactions, you can send a byte to wake up GAP instead of running the above command.

Note

Command arguments are positional arguments meaning that you must respect the order !

Warning

Please check the features below to be aware of potential restrictions as platform compatibility.

Features

Check GAP CLI status
Flashing a binary file
- On MRAM
- On OctoSPI (not working yet)
SSBL / OTA
- On MRAM
- On OctoSPI (not working yet)
- Open
- Update a partition
  Simple or full update
  
  With or without encryption
- Close
Load key
Secure CLI
Enable JTAG
Set power parameters
- Frequencies
- Voltage (only on board for now)
Control sleep modes
- Deep sleep
  Wake up from RTC
  
  Wake up from GPIO (only on board)
  
  Wake up from UART (only on board for now)
- Deep sleep retentive
  Wake up from RTC
  
  Wake up from GPIO (only on board)
  
  Wake up from UART (only on board for now)
- Light sleep
  Wake up from RTC
  
  Wake up from GPIO (only on board)
  
  Wake up from UART (only on board for now)