SAM-BA Scripting Documentation

Scripting SAM-BA

SAM-BA uses Qt5 QML language for scripting.

Running a SAM-BA script

SAM-BA scripts are QML scripts and can be loaded using the sam-ba command-line tool.

For example, to run 'my-script.qml', the following command line is used: sam-ba -x my-script.qml

Initial QML script

This minimal QML script shows how to react to script loading and unloading. This mechanism is used by all the SAM-BA scripts:

import QtQuick 2.3

Item {
        Component.onCompleted: print("Script started")
        Component.onDestruction: print("Script completed")
}

This example uses QML signals to react to events: when the script is loaded, the message "Script started" is displayed. When the script is unloaded, the message "Script completed" is displayed.

Connecting to a device

To connect to a device, an instance of Connection must be used. The Connection type contains methods to read/write memory on the device and make it execute code.

In this example, a SerialConnection is used:

import SAMBA 3.7
import SAMBA.Connection.Serial 3.7

SerialConnection {
        onConnectionOpened: print("Connection opened")
        onConnectionFailed: print("Connection failed: " + message)
        onConnectionClosed: print("Connection closed")
}

This script instanciates a serial connection with its default properties. In particular, the autoConnect property that defaults to true will trigger an automatic connection once the QML object is created.

This will in turn trigger one of the onConnectionOpened or onConnectionFailed signals and display a message.

When the script completes, the connection will be automatically closed. This will trigger the onConnectionClosed signal and display a final message.

Using SAM-BA Applets

The Connection object provides several functions to load applets and make tha currently loaded applet to execute commands.

The applet must first be loaded using the initializeApplet function. This function will upload the applet code to the device, call the initialization function and update the applet property of the connection.

In this example, a SerialConnection is used to load the serialflash applet on a SAMA5D2 Xplained Ultra board and the applet erase function is called:

import SAMBA 3.7
import SAMBA.Connection.Serial 3.7
import SAMBA.Device.SAMA5D2 3.7

SerialConnection {
        device: SAMA5D2Xplained {}
        onConnectionOpened: {
                initializeApplet("serialflash")
                applet.erase()
        }
}

More QML examples

The examples directory in the SAM-BA distribution contains more advanced examples.

It is recommended to start by reading and modifying the provided examples, then to refer to the SAM-BA API Reference and QML Reference.

SAM-BA API Reference