SAM-BA® In-System Programmer - Host Application Program

Last modified by Microchip on 2024/06/20 12:33

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.

Back to Top

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.).

Directory Structure

Back to Top

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


Back to Top

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.

SAM-BA In-System Programmer Block Diagram

Note: Add the SAM-BA directory to the PATH of your environment variables so that you can execute SAM-BA Host commands from your project directories.

Caution: Command line options are subject to change between versions of the SAM-BA Host application program.

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

Back to Top

Host to Monitor Serial Communications

The SAM-BA Host application program communicates with the target's SAM-BA Monitor program over a serial port.

Note: The SAM-BA Host to Monitor serial communications link is a dedicated serial port separate from the Target Console serial communications.

SAM-BA In-System Programmer Block Diagram

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).

Note: For specific information on the operation of the SAM-BA Monitor of a particular device, refer to the device datasheet.

Back to Top

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).

SAM-BA In-System Programmer ATSAMA5D27-SOM1-EK1 Block Diagram

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).

SAM-BA In-System Programmer SAM9X60-EK Block Diagram

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.

Back to Top

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.

Note: The -p, --port option should be provided when using the -m, --monitor or the -a, --applet option. If the -p, --port option is omitted, the serial connection is chosen by default.

Alert: The -p, --port option should not be used with the -e, --execute option since the QML script already specifies which port will be used.

The available port options are listed by adding help in the argument:

$ sam-ba --port help
Known ports: serial, j-link, secure

Back to Top

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

Alert: JTAG access is disabled during the execution of the ROM Boot Code. It is re-enabled when the ROM Boot Code jumps to the second-stage bootloader, or when it launches the SAM-BA monitor, or no boot file has been found in any external Flash memory.

Back to Top

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.

Alert: 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 attain confidential documents.

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)

Alert:  JTAG access is disabled during the execution of the ROM Boot Code. It is re-enabled when the ROM Boot Code jumps to the second-stage bootloader, or when it launches the SAM-BA monitor, or no boot file has been found in any external Flash memory.

Back to Top

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.

Note: By default, the SAM-BA Host selects the first SAM-ICE™ interface probed on the host computer. However, when many SAM-ICE peripherals are connected to the host computer, a serial-number can be passed on the command line to selected the correct one.

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)

Note: JTAG interface was designed for chip and board testing. It is used for boundary scans, checking faults in chips/boards in production. Debugging and flashing micros was an evolution in its application over time.

Note: Serial Wire Debug (SWD) is an ARM-specific protocol designed specifically for debugging. It is a 2-pin (SWDIO/SWCLK) electrical alternative to the JTAG interface.

Back to Top

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>

Alert: DO NOT use the Execute e, --execute option on the same command line with the Monitor -m, --monitor, Applet -a, --applet, Port -p, --port, Device -d, --device, or Board -b, --board options. However, it can be used with the Tracelevel -t, --tracelevel option.

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.

Learn More

Back to Top