Home ·

- SAM-BA Scripting Documentation

# 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

Module | Description
--- | ---
SAMBA Module | Contains common SAM-BA types and utilities
SAMBA.Connection.JLink Module | Contains support for connecting to devices using JTAG
SAMBA.Connection.Serial Module | Contains support for connection to devices using USB/Serial
SAMBA.Device.PIC32CXMT Module | Contains support for PIC32CXMT device
SAMBA.Device.SAM9xx5 Module | Contains support for SAM9xx5 device
SAMBA.Device.SAM9X60 Module | Contains support for SAM9X60 device
SAMBA.Device.SAM9X7 Module | Contains support for SAM9X7x device
SAMBA.Device.SAMA5D2 Module | Contains support for SAMA5D2 device
SAMBA.Device.SAMA5D3 Module | Contains support for SAMA5D3 device
SAMBA.Device.SAMA5D4 Module | Contains support for SAMA5D4 device
SAMBA.Device.SAMA7G5 Module | Contains support for SAMA7G5 device