SAM-BA® In-System Programmer - Host Application Program
Introduction
The SAM-BA® Host is an open-source software application program that runs on a host PC running Windows® or Linux®. It communicates with the target device (Arm®-based Microchip MPU or MCU) which has the SAM-BA Monitor program embedded in its ROM Boot Code. In addition, the SAM-BA Host and Monitor can load and execute binary applet programs in RAM of the target device to provide additional features and capabilities. Finally, the SAM-BA Host can execute Qt Modeling Language (QML) scripts to combine many low-level commands to simplify development and debugging.
Installation
Download the SAM-BA Host application program.
The SAM-BA Host program is provided under the GNU General Public License version 2. A copy of the license can be found in the LICENSE.txt file.
The SAM-BA Host application program can run on Windows or Linux operating systems.
Windows
The Windows version will run on 32-bit and 64-bit platforms. Download the ZIP file and unzip it into a working directory of your choice. Add the SAM-BA directory path to the environment variables.
Once the SAM-BA Host program has been installed, the execution of the application is from the Windows command prompt. Change the directory to the location of the SAM-BA directory. The available options can be found by executing the sam-ba.exe -help option.
Linux
The Linux version will run on 64-bit platforms. Download the *.tar.gz file and extract it into a working directory of your choice. Add the SAM-BA directory path to the environment variables.
Once the SAM-BA Host program has been installed, the execution of the application is from the command line. Open a terminal window and change the directory to the location of the SAM-BA directory. The available options can be found by executing the sam-ba.exe -help option.
Directory Structure
Both Windows and Linux versions have similar directory structure:
- doc: SAM-BA documentation provided in html format. Open ../doc/index.html to begin.
- examples: Example QML script files organized by the target device. Refer to the README.txt in each of the example directories.
- lib: Executable files and libraries (Linux only).
- qml: QML plugins (devices, communication, etc.).
Secure
The SAMA5D2 Series and SAM9X60 have the ability to load signed and encrypted programs during the boot process. This allows only authorized code to load and execute on the processor. Enabling the ROM boot code for Secure Boot mode requires a Non-Disclosure Agreement (NDA) from Microchip Technology. Contact your nearest Microchip Sales office for instructions on how to obtain confidential documents:
- AN2435, SAMA5D2 Series Secure Boot Strategy, document number: DS00002435
- SAM9X60 Secure Boot Stategy, document number: DS00003195
Command Line Interface
Control of the SAM-BA host application program is from the command line. If you are using Windows, open a command prompt. If you are using Linux, open a terminal window.
Help [-h, --help] Option
The help -h, --help option will print out the available commands specific to the version of the SAM-BA host application program.
$sam-ba –-help SAM-BA Command Line Tool v3.3.1 Copyright 2018 Microchip Technology Usage: sam-ba [options] Options: -v, --version Displays version information. -h, --help Displays this help. -t, --tracelevel <trace_level> Set trace level to <trace_level>. -x, --execute <script.qml> Execute script <script.qml>. -p, --port <port[:options:...]> Communicate with device using <port>. -d, --device <device[:options:...]> Connected device is <device>. -b, --board <board[:options:...]> Connected board is <board>. -m, --monitor <command[:options:...]> Run monitor command <command>. -a, --applet <applet[:options:...]> Load and initialize applet <applet>. -c, --command <command[:args:...]> Run command <command>. -w, --working-directory <DIR> Set working directory to <DIR>.
Port [-p, --port] Option
The SAM-BA host application program communicates with the target device which has the SAM-BA monitor program embedded in its ROM boot code. Setup of the host to monitor serial communications is performed with the -p, --port option. For additional information, see the "Host to Monitor Serial Communications" section of the of "SAM-BA In-System Programmer - Host Application Program" page.
Device [-d, --device] and Board [-b, --board] Options
The SAM-BA host application program is configured to communicate with specific targets using the -d, --device and -b, --board options. For additional information, see the "SAM-BA In System Programmer - Supported Devices and Evaluation Kits" page.
Monitor [-m, --monitor] Option
SAM-BA monitor commands can be executed from the SAM-BA host application program using the -m, --monitor option. For additional information, see the "Monitor Commands" section of the "SAM-BA In-System Programmer Monitor" page.
Applet [-a, --applet] Option
The SAM-BA host application program can load and execute binary Applet programs in the target device RAM to provide additional features and capabilities using the -a, --applet option. For more information, see the "SAM-BA In-System Programmer - Applets" page.
Tracelevel [-t, --tracelevel] Option
SAM-BA Applet programs can provide status and logging information through the Target Console. The verbosity can be set with the -t, --tracelevel options. For more information, see the "SAM-BA In-System Programmer Target Console Communications" page.
Execute [-x, --execute] and Command [-c, --command] Options
The SAM-BA host can execute Qt Modeling Language (QML) scripts to combine many low-level commands to simplify development and debugging using the -x, --execute and -c, --command options. For more information, see the "SAM-BA In-System Programmer - Host Application Program" page.
Additional help information can be found for each of the individual options adding the help argument. For example:
$ sam-ba --port help Known ports: serial, j-link, secure
Host to Monitor Serial Communications
The SAM-BA Host application program communicates with the target's SAM-BA Monitor program over a serial port.
The choice of serial communications port on the target device depends on the SAM-BA Monitor embedded in the device. For example, the SAM-BA Monitor in the SAMA5D2 Series MPUs will initialize the Universal Asynchronous Receiver Transmitter (UART) pins (Target Console) and the USB High-Speed Device Port (UDPHS). If the USB Device port has enumerated, the SAM-BA Monitor waits for a command. Otherwise, it waits for a command from the UART (Console).
Connecting Host to Target (ATSAMA5D27-SOM1-EK1)
Connect the host PC to the USB High-Speed Device Port (J17) using a USB Micro-B connector. Ensure there is no SD Memory Card installed in the evaluation kit. The host PC will enumerate the port as a USB Communication Device Class (CDC).
Connecting Host to Target (SAM9X60-EK)
Connect the host PC to the USB 2.0 Port (J7) using a USB Micro-B connector. Ensure there is no SD Memory Card installed in the evaluation kit. The host PC will enumerate the port as a USB Communication Device Class (CDC).
You can locate the USB port by:
Windows
Open the Windows Device Manager and expand Ports (COM & LPT).
Mac OS®
Open the terminal emulation program and observe the available ports in the setup menu, or
In a command window, type: $ ls /dev/tty.*.
Linux
In a command window, type: $ dmesg.
Port [-p, --port] Option
The -p, --port option configures the communications port of the SAM-BA Host application program to the embedded SAM-BA Monitor program running on the target device.
The available port options are listed by adding help in the argument:
$ sam-ba --port help Known ports: serial, j-link, secure
serial
The sam-ba --port serial command connects the SAM-BA Host application serial communications port to the SAM-BA Monitor running on the target device.
By default, the SAM-BA Host attempts to connect to AT91 USB, if it is available. Otherwise, it will attempt to connect to the DBUG/UART/USART (depending on the target device) communication port. Alternatively, the serial port can be explicitly configured from the command line.
The sam-ba --port serial:help command displays all supported serial port options:
$ sam-ba --port serial:help
Syntax:
serial:[<port>]:[<baudrate>]
Examples:
serial serial port (will use first AT91 USB if found otherwise first serial port)
serial:COM80 serial port on COM80
serial:ttyUSB0:57600 serial port on /dev/ttyUSB0, baudrate 57600
secure
The sam-ba --port secure command connects the SAM-BA Host application serial communications port to the SAM-BA Monitor running on the target device.
The SAMA5D2 Series and SAM9X60 have the ability to load signed and encrypted programs during the Boot Process. This allows only authorized code to load and execute on the processor.
The sam-ba --port secure:help command displays all supported secure port options:
$ sam-ba --port secure:help
Syntax:
secure:[<port>]:[<baudrate>]:[<verbose>]
Examples:
secure serial port (will use first AT91 USB if found otherwise first serial port)
secure:COM80 serial port on COM80
secure:ttyACM0 serial port on /dev/ttyACM0
secure:::1 serial port (display communication between sam-ba and the secure SAM-BA monitor of the target)
j-link
The sam-ba --port j-link command connects the SAM-BA Host application SEGGER J-Link debugger port to the SAM-BA Monitor running on the target device.
The sam-ba --port j-link:help command displays all supported j-link port options:
$ sam-ba --port j-link:help
Syntax:
j-link:[<S/N>]:[swd|jtag]:[<speed in kHz>]
Examples:
j-link use first J-Link device found
j-link:123456 use J-Link with serial number 123456
j-link:123456:swd use J-Link with serial number 123456, in SWD mode
j-link::swd use first J-Link device found, in SWD mode
j-link::jtag use first J-Link device found, in JTAG mode (JTAG mode is the default)
j-link::jtag:150 use first J-Link device found, in JTAG mode at 150kHz (default is 0 for auto)
QML Scripts
The SAM-BA Host can execute Qt Modeling Language (QML) scripts to combine many low-level commands to simplify development and debugging.
The -x, --executeoption must be followed by the filename of the QML script to be executed. There are no additional parameters.
$ sam-ba -x <qmlfile>
QML Script Examples
Documentation on writing QML scripts is located in the ../doc/scripting.html document directory. Example scripts are located in the ../qml/ directory.