Home ·

# Connection QML Type

The Connection type represents a physical connection to a programmable device. More...

Import Statement: | import SAMBA 3.7
Inherited By: | JLinkConnection and SerialConnection

- List of all members, including inherited members

## Properties

- aliases : var
- applet : var
- appletConnectionType : var
- autoConnect : bool
- autoDeviceInit : bool
- device : var
- mailbox : var
- name : var
- priority : var

## Signals

- connectionClosed()
- connectionFailed(string message)
- connectionOpened()

## Methods

- ByteArray appletBufferRead(int length)
- bool appletBufferWrite(ByteArray data)
- int appletExecute(AppletCommand command, var arguments)
- int appletMailboxRead(int index)
- bool appletMailboxReceive(int timeout)
- bool appletMailboxSend()
- bool appletUpload(Applet applet)
- void close()
- void defaultAppletExecute(AppletCommand command, var arguments)
- string getDeviceVersion()
- bool go(int address)
- void initializeApplet(string appletName)
- void open()
- ByteArray read(int address, int length)
- int readu8(int address, int timeout)
- int readu16(int address, int timeout)
- int readu32(int address, int timeout)
- bool toSecureMonitor()
- bool waitForMonitor(int timeout)
- bool write(int address, ByteArray data)
- bool writeu8(int address, int data)
- bool writeu16(int address, int data)
- bool writeu32(int address, int data)

## Detailed Description

This type contains methods to communicate with a device:

- reading/writing memory
- requesting execution of code
- basic functions to load and execute applets

It is only intended to define the method prototypes and does not communicate with anything. Please use any of the types that inherit from Connection for actual usable implementations.

### Reading and Writing Memory

The following methods are provided to read and write to memory:

Name | Description
--- | ---
read | Reads a memory block
readu8 | Reads single unsigned byte
readu16 | Reads single unsigned 16-bit word
readu32 | Reads single unsigned 32-bit word
write | Writes a memory block
writeu8 | Writes single unsigned byte
writeu16 | Writes single unsigned 16-bit word
writeu32 | Writes single unsigned 32-bit word

For example, to read a 32-bit unsigned word at address 0x12345678:

    var data = connection.readu32(0x12345678)

To write unsigned 32-bit value 0x42 to address 0x12345678:

    connection.writeu32(0x12345678, 0x42)

### Executing Code

The `go` method can be used to execute code on the device. It make the CPU jump to the given address. Please note that depending on the communication method, the executed code may have to give the control back to its caller. SAM-BA Applets contain such code to give back control to SAM-BA Monitor.

For example, to execute code at address 0x12345678:

    connection.go(0x12345678)

### Loading and Running Applets

The Connection type also contains methods to load and execute applets (see Applet for more information on SAM-BA applets). The methods related to applet handling are:

Name | Description
--- | ---
appletUpload | Upload the applet code to the device
appletMailboxRead | Reads single unsigned 32-bit word from the mailbox
appletBufferRead | Reads a block from the applet buffer
appletBufferWrite | Writes a block into the applet buffer
appletExecute | Writes parameters in the applet mailbox and execute the applet code

For example, to load and initialize an applet:

    connection.appletUpload(applet)
    connection.appletExecute("init")

This example assumes that:

- the applet initialization command is named "init"
- it takes no arguments

To read a 0x42 bytes block at offset 0x1234 from a "memory" applet:

    connection.appletExecute("read", [ connection.applet.bufferAddr, 0x42, 0x1234 ])
    var block = connection.appletBufferRead(0x42)

This example assumes that:

- the applet has already been loaded/intialized
- its read command is named "read" and that it takes as arguments the buffer address, the number of bytes to read and the starting address

## Property Documentation

aliases : var

The connection aliases (alternate names that can be used on the command-line)

applet : var

The current applet, or `undefined` if no applet is loaded.

appletConnectionType : var

The connection type value passed at applet initialization

autoConnect : bool

Connection automatic connection flag

Whether the connection should be automatically established once the Connection QML object is ready.

autoDeviceInit : bool

Connection automatic device initialization flag

Whether the device initialize() function should be automatically called once the connection is opened.

device : var

Device whose applets will be used

mailbox : var

The applet mailbox, or `undefined` if the applet has not been executed yet.

name : var

The connection name

priority : var

The connection priority value

The connection with the lowest priority is selected by default when no connection parameter is provided on the command-line.

## Signal Documentation

connectionClosed()

This signal is triggered when the connection has been closed.

connectionFailed(string message)

This signal is triggered when the connection failed to open.

The message parameter contains the failure cause.

connectionOpened()

This signal is triggered when the connection has been opened successfully.

## Method Documentation

ByteArray appletBufferRead(int length)

Reads length bytes from the applet buffer.

Returns the data on success, `undefined` if an error occurred or if the requested length is greater than the current applet buffer size.

bool appletBufferWrite(ByteArray data)

Writes data into the applet buffer.

Returns true on success, false if an error occurred or if the data length is greater than the current applet buffer.

int appletExecute(AppletCommand command, var arguments)

Execute applet command with arguments and poll for completion until the command has completed or its timeout is expired.

Arguments can be supplied a single integer if there is only one argument, or an array of integers if multiple arguments are needed.

After an applet command is started, the Connection will poll for applet completion until the requested timeout is expired.

Returns the applet return code. Zero (0) is usually means success and anything else is an error. The values of the error codes are applet-specific. No value is returned if no applet is loaded, if the arguments types are invalid or if the applet command has not completed before the timeout was reached.

int appletMailboxRead(int index)

Reads unsigned 32-bit word at index index in the applet mailbox.

bool appletMailboxReceive(int timeout)

Receive the content of the applet mailbox.

Returns true on success, false otherwise.

bool appletMailboxSend()

Send the content of the applet mailbox.

Returns true on success, false otherwise.

bool appletUpload(Applet applet)

Uploads an applet to the device.

The applet code is written at the applet `codeAddr` but no code is executed.

Returns true on success, false otherwise.

void close()

Closes the connection.

The connectionClosed signal will be raised when the connection is closed.

void defaultAppletExecute(AppletCommand command, var arguments)

Default implementation for Connection::appletExecute()

Returns the applet return code. No value is returned if no applet is loaded, if the arguments types are invalid or if the applet command has not completed before the timeout was reached.

string getDeviceVersion()

Read the ROM version from the target device

Returns the ROM version string.

bool go(int address)

Execute code at address address.

Returns true on success, false otherwise.

void initializeApplet(string appletName)

Loads and initializes the appletName applet for the currently selected device.

Throws an Error if the applet is not found or could not be loaded/initialized.

void open()

Opens the connection.

On success, the connectionOpened signal will be raised. If an error occurrs, the connectionFailed signal will be raised with the failure cause as argument.

ByteArray read(int address, int length)

Read length bytes at address address.

Returns a ByteArray with the data or undefined if an error occured or if no data could be read after timeout milliseconds.

int readu8(int address, int timeout)

Read a single unsigned byte at the given address.

Returns the unsigned byte read at address or undefined if an error occured or if no value could be read after timeout milliseconds.

int readu16(int address, int timeout)

Read a single unsigned 16-bit word at the given address.

Returns the unsigned 16-bit word read at address or undefined if an error occured or if no value could be read after timeout milliseconds.

int readu32(int address, int timeout)

Read a single unsigned 32-bit word at the given address.

Returns the unsigned 32-bit word read at address or undefined if an error occured or if no value could be read after timeout milliseconds.

bool toSecureMonitor()

Tells whether we connect to the secure SAM-BA monitor.

Returns true if the connection is established to the secure SAM-BA monitor, false otherwise.

bool waitForMonitor(int timeout)

Wait timeout milliseconds for monitor to be ready

Some connection plugins do no implement this feature and will return true even when the monitor is not yet ready.

Returns true on success, false otherwise.

bool write(int address, ByteArray data)

Write byte array data at address address.

Returns true on success, false otherwise.

bool writeu8(int address, int data)

Write unsigned byte data at address address.

Returns true on success, false otherwise.

bool writeu16(int address, int data)

Write unsigned 16-bit word data at address address.

Returns true on success, false otherwise.

bool writeu32(int address, int data)

Write unsigned 32-bit word data at address address.

Returns true on success, false otherwise.