RTT

The pc-nrfjprog-js.RTT module exposes the functionality to the RTT functionality. RTT is a high-speed protocol specified by SEGGER, available on all Nordic Semiconductor development kits with a SEGGER chip. More details about the protocol may be found at SEGGERS product pages: Real Time Transfer.

RTT works on the principle that the firmware sets up a buffer in RAM which it populates with UP and DOWN circular buffers. A device may have multiple up and down buffers, called channels.

When you want to write to a device, you choose a down channel and write data to it. The RTT protocol will then copy the data into the chosen buffer of the chosen channel and update the end pointer for that buffer. The firmware will subsequently detect that there is new data in the buffer and can then read it.

When you want to read from a device, the firmware chooses an up channel and writes data to it. The RTT protocol will write data to the end of the buffer and update the end pointer for the buffer of the chosen channel. When you subsequently read on that up channel, you will get the data in the buffer, up to the specified amount of data you specified, and the start pointer for the buffer will be updated.

Due to nRFjprog resetting the device for all device specific function calls, they may NOT be performed simultaneously.

You may at any time have at most one RTT connection open.

Source:

Example

nrfjprogjs.rttStart(12345678, {}, function(err, down, up) {
     nrfjprogjs.rttWrite(12345678, 0, 'Some data to write', function(err, length, timeSinceRTTStartInUs) {
         nrfjprogjs.rttRead(12345678, 0, 100, function(err, stringData, rawData, timeSinceRTTStartInUs) {
             nrfjprogjs.rttStop(12345678, function(err) {
                 console.log('Stopped');
             });
         });
     });
});

Methods

(static) rttRead(serialNumber, channelIndex, length, callback)

Async function to read RTT contents from an up channel on the device. You read on the up channel specified by the channelIndex. The callback function can access a UTF-8 string representation of the RTT message (stringData in the example) if UTF-8 encoding is possible, as well as an array (rawData in the example) containing the byte values (as integers between 0 and 255), plus the time elapsed since RTT was started, in microseconds.

This function will read up to length number of bytes and return them as both String and an array of the raw bytes. If the content of the channel is empty, the returned string and array will be empty.

Source:
Parameters:
Name Type Description
serialNumber integer The serial number of the device to read RTT on
channelIndex integer The RTT up channel index to read from
length integer The max amout of bytes to read
callback function A callback function to handle the async response. It shall expect four parameters: (Error, String, Array of Integers, integer)
Example
nrfjprogjs.rttRead(12345678, 0, 100, function(err, stringData, rawData, timeSinceRTTStartInUs) {
     if (err) throw err;
     console.log(stringData);
     console.log(rawData);
     console.log('Time since start of RTT in micro seconds:', timeSinceRTTStartInUs)
});

(static) rttStart(serialNumber, startOptions, callback)

Async function to start RTT.

This function will attempt to open an RTT connection to the device with serialnumber serialNumber. It will return an Error if the device does not exist or if its firmware doesn't support RTT.

The RTT protocol uses down channels to write to the device and up channels to read from the device.

You can only open RTT on one device at any given time.

When you have an open RTT session, you should not call any functions in pc-nrfjprog-js, as these will reset the device.

When you are done with the RTT session, you should call stop().

Source:
Parameters:
Name Type Description
serialNumber integer The serial number of the device to start RTT on
startOptions StartOptions A plain object containing options about how to start RTT
callback function A callback function to handle the async response. It shall expect three parameters: (Error, Array of ChannelInfo, Array of ChannelInfo)
Example
nrfjprogjs.rttStart(12345678, {}, function(err, down, up) {
     if (err) console.error('The firmware is not RTT capable');

     console.log('Down channels');
     down.map(function(channel) {
            console.log('Index:', channel.channelIndex);
            console.log('Direction:', channel.direction);
            console.log('Name:', channel.name);
            console.log('Size:', channel.size);
     });

     console.log('Up channels');
     up.map(function(channel) {
            console.log('Index:', channel.channelIndex);
            console.log('Direction:', channel.direction);
            console.log('Name:', channel.name);
            console.log('Size:', channel.size);
     });
});

(static) rttStop(serialNumber, callback)

Async function to stop RTT.
Source:
Parameters:
Name Type Description
serialNumber integer The serial number of the device to stop RTT on
callback function A callback function to handle the async response. It shall expect one parameter: (Error)
Example
nrfjprogjs.rttStop(12345678, function(err) {
    if (err) console.error('Stopping RTT failed');
});

(static) rttWrite(serialNumber, channelIndex, data, callback)

Async function to write data to a down channel on the device. You write on the down channel specified by the channelIndex. The data written may either be a string or an array of integers. String data will be UTF8 encoded.
Source:
Parameters:
Name Type Description
serialNumber integer The serial number of the device to write RTT on
channelIndex integer The RTT down channel index to write to
data string | Array.<integer> The data to send
callback function A callback function to handle the async response. It shall expect three parameters: (Error, integer, integer)
Examples
nrfjprogjs.rttWrite(12345678, 0, 'Start command', function(err, length, timeSinceRTTStartInUs) {
     if (err) throw err;
     console.log('Amount of bytes written', length);
     console.log('Time since start of RTT in micro seconds:', timeSinceRTTStartInUs)
});
nrfjprogjs.rttWrite(12345678, 0, [0, 1, 2, 3, 4], function(err, length, timeSinceRTTStartInUs) {
     if (err) throw err;
     console.log('Amount of bytes written', length);
     console.log('Time since start of RTT in micro seconds:', timeSinceRTTStartInUs)
});

Type Definitions

ChannelInfo

Information about the different up and down channels available on the device. A down channel is a channel from the computer to the device. An up channel is a channel from the device to the computer.
Properties:
Name Type Description
channelIndex integer The index used to address this channel
direction integer The direction of the channel. Value will be one of nrfjprogjs.UP_DIRECTION or nrfjprogjs.DOWN_DIRECTION
name String The name of the channel
size integer The size of the channel
Source:

Error

Possible error.
If an operation completed sucessfully, the error passed to the callback function will be undefined (and thus, falsy).
This will be an instance of the built-in Error class, with some extra properties:
Properties:
Name Type Description
errno integer The error number. Value will be one of the following predefined constants:
nrfjprogjs.RTTCouldNotLoadHighlevelLibrary
nrfjprogjs.RTTCouldNotOpenHighlevelLibrary
nrfjprogjs.RTTCouldNotGetDeviceInformation
nrfjprogjs.RTTCouldNotLoadnRFjprogLibrary
nrfjprogjs.RTTCouldNotOpennRFjprogLibrary
nrfjprogjs.RTTCouldNotConnectToDevice
nrfjprogjs.RTTCouldNotStartRTT
nrfjprogjs.RTTCouldNotFindControlBlock
nrfjprogjs.RTTCouldNotGetChannelInformation
nrfjprogjs.RTTCouldNotCallFunction
nrfjprogjs.RTTNotInitialized
nrfjprogjs.RTTCouldNotExecuteDueToLoad
errcode String A human-readable version of the error code.
erroroperation String The internal function that caused the error.
errmsg String Error string. The value will be equal to that of the built-in message property.
lowlevelErrorNo integer The low-level error code, if applicable.
lowlevelError String A human-readable version of the low-level error code.
log String The complete log from the internal functions.
Source:
Type:
  • Error
Examples
nrfjprogjs.rttStart(12345678, {}, function(err, down, up) {
    if (err) {
        throw err;
    } else {
        // success
    }
});
nrfjprogjs.rttStart(12345678, {}, function(err, down, up) {
    if (err && err.errno === nrfjprogjs.RTTCouldNotFindControlBlock) {
         console.error('The firmware is not RTT capable');
    }
});

StartOptions

Option flags to be used when starting RTT. This may speed up the process of locating the control block, and the RTT Start. If controlBlockLocation specified, only that location will be searched for the RTT control block, and an error will be returned if no control block where found. If no value is specified for controlBlockLocation, the RAM will be searched for the location of the RTT control block.
Properties:
Name Type Attributes Description
controlBlockLocation integer <optional>
 The location of the control block. If this location is not the start of the RTT control block, start will fail.
Source: