pc-nrfjprog-js - Documentation

The pc-nrfjprog-js module exposes the functionality to the nRF5x Command-line tools to your nodeJS programs.

Source:

api.js, line 45

Example

const nrfjprogjs = require('pc-nrfjprog-js');

nrfjprogjs.getConnectedDevices(function(err, devices) {
    console.log('There are ' + devices.length + ' nRF devices connected.');
});

Methods

(static) close(serialNumber, callback)

Async function to close a connection to a device opened by open.

Source:

api.js, line 692

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to close
`callback`	`function`	A callback function to handle the async response. It shall expect one parameter: (Error).

(static) erase(serialNumber, options, progressCallbackopt, callback)

Async function to erase a chunk of memory.
This is the same functionality as running "nrfjprog --erasepage" in the command-line tools.
Will not erase a locked device. To erase a locked device, use recover

Source:

api.js, line 585

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		The serial number of the device
`options`	`module:pc-nrfjprog-js~EraseOptions`		Options on how to erase the device memory
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

(static) getConnectedDevices(callback)

Async function to get a list of all connected devices.

Source:

api.js, line 328

Parameters:

Name	Type	Description
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, Array of SerialNumberAndDeviceInformation).

Example

nrfjprogjs.getConnectedDevices( function(err, devices) {
     if (err) throw err;
     for (let i = 0; i < devices.length; i++) {
         console.log(
             devices[i].serialNumber +
             ' has ' +
             devices[i].deviceInfo.ramSize +
             ' bytes of RAM'
         );
     }
});

(static) getDeviceInfo(serialNumber, callback)

Async function to get information of a single device, given its serial number.

Source:

api.js, line 359

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to query
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, DeviceInformation).

Example

nrfjprogjs.getDeviceInfo(123456789, function(err, info) {
     if (err) throw err;
     console.log('Selected device has' + info.ramSize + ' bytes of RAM');
});

(static) getDllVersion()

Alias to getLibraryVersion.

Deprecated:

Use getLibraryVersion instead.

Source:

api.js, line 293

(static) getLibraryInfo(serialNumber, callback)

Async function to get information about the low level library used by the device, given its serial number.

Source:

api.js, line 393

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to query
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, LibraryInformation).

Example

nrfjprogjs.getLibraryInfo(123456789, function(err, info) {
     if (err) throw err;
     console.log('Selected device uses ' + info.path + ' to connect');
});

(static) getLibraryVersion(callback)

Async function to get the version of the nrfjprog library in use.

Source:

api.js, line 307

Parameters:

Name	Type	Description
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, Version).

Example

nrfjprogjs.getLibraryVersion( function(err, version) {
     if (err) throw err;
     console.log( version.major + '.' + version.minor + '.' + version.revision ) // e.g. 9.6.0
});

(static) getProbeInfo(serialNumber, callback)

Async function to get information of a single device, given its serial number.

Source:

api.js, line 376

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to query
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, ProbeInformation).

Example

nrfjprogjs.getProbeInfo(123456789, function(err, info) {
     if (err) throw err;
     console.log('Selected device has the following clockspeed ' + info.clockSpeedkHz + 'kHz');
});

(static) getSerialNumbers(callback)

Async function to get the serial numbers of all connected devices.

Source:

api.js, line 344

Parameters:

Name	Type	Description
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, Array of {integer}.

Example

nrfjprogjs.getSerialNumbers(function(err, serialNumbers) {
     if (err) throw err;
     for (let i = 0; i < serialNumbers.length; i++) {
         console.log(serialNumbers[i]);
     }
});

(static) open(serialNumber, callback)

Async function to open (and keep open) a connection to a device. By default, all other function calls implicitly open a connection, perform an operation, reset the device and close the connection to the device.
This can impact performance negatively. In order to prevent the extra steps (open, reset, close), one can explicitly open() and close() a connection to a device. This will keep a connection open, allowing all other function calls to execute faster, and resetting the device only once (when the connection is closed).
Open connections shall be closed by calling close If a connection to a device is opened, then all subsequent calls will use the already-opened connection. Opening a connection twice will close the first connection and return an error. Closing a connection twice will close it on the first `close()` call: the second one will have no effect.

Source:

api.js, line 682

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to open
`callback`	`function`	A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.read(123456789, 0, function(err, data) {

  nrfjprogjs.read(123456789, 0x0000, 0x1000, function(err1, data1) {
    if (err1) throw err;

    nrfjprogjs.read(123456789, 0x1000, 0x1000, function(err2, data2) {
      if (err2) throw err;

      nrfjprogjs.close(123456789, function() {});
    } );
  } );
});

(static) program(serialNumber, filename, options, progressCallbackopt, callback)

Async function to push a program to the device.
This is the same functionality as running "nrfjprog --program" in the command-line tools.
If the ProgramOption chip_erase_mode is ERASE_ALL, this function will recover the device if it initially is not allowed to program the device due to protection.

Source:

api.js, line 478

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		The serial number of the device to program
`filename`	`string`		Either the filename of the `.hex` file containing the program, or the contents of such a file.
`options`	`module:pc-nrfjprog-js~ProgramOptions`		A plain object containing options about how to push the program.
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.program(123456789, "/some/path/nrf52832_abcd.hex", {}, function(err) {
     if (err) throw err;
});

(static) programDFU(serialNumber, filename, progressCallbackopt, callback)

Async function to push a DFU update to the modem coprocessor of the device.

Source:

api.js, line 496

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		The serial number of the device to program
`filename`	`string`		The filename of the `.zip` file containing the update.
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.programDFU(123456789, "/some/path/nrf52832_abcd.zip", function(err) {
     if (err) throw err;
});

(static) programMcuBootDFU(serialNumber, filename, uart, timeout, progressCallbackopt, callback)

Async function to push a DFU update to a mcuboot based device in serial recovery mode.

Source:

api.js, line 520

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		Fake serial number, must be non zero
`filename`	`string`		Filename of the `.hex` file containing the mcuboot update
`uart`	`string`		The connected device UART
`timeout`	`integer`		Timeout in milliseconds. For DFU it must be more than 11000 because of response time when starting programming
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.programMcuBootDFU(-1, "/some/path/nrf52832_abcd.hex", "COM1", 15000,
    function(progress) {
        console.log(progress);
    },
    function(err) {
        if (err) throw err;
    }
);

(static) read(serialNumber, address, length, callback)

Async function to read a chunk of memory. The data received by the callback is an array of integers, each of them representing a single byte (with values from 0 to 255).
The read operation happens without verifying that the addresses are accessible or even exist. Note that if the target address is in unpowered RAM, the operation will fail.
Please note that the data is an array of numbers - it is NOT a UInt8Array, and it is NOT a Buffer.
This is the same functionality as running "nrfjprog --memrd" in the command-line tools.

Source:

api.js, line 423

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to read memory from
`address`	`integer`	The start address of the block of memory to be read
`length`	`integer`	The amount of bytes to be read
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, Array of integers).

Example

nrfjprogjs.read(123456789, 0, 16, function(err, data) {
     if (err) throw err;
     console.log('The first 16 bytes of memory look like: ' + data.join(','));
});

(static) readToFile(serialNumber, filename, options, progressCallbackopt, callback)

Async function to read memory from the device and write the results into a file.
The read operation happens without verifying that the addresses are accessible or even exist. Note that if the target address is in unpowered RAM, the operation will fail.
This is the same functionality as running "nrfjprog --readcode" in the command-line tools.

Source:

api.js, line 544

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		The serial number of the device to read
`filename`	`string`		The filename of the `.hex` file where the content of the device should be stored.
`options`	`module:pc-nrfjprog-js~ReadToFileOptions`		A plain object containing options about what to read.
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.readToFile(123456789, "/some/path/to/store/file.hex", {}, function(err) {
     if (err) throw err;
});

(static) readU32(serialNumber, address, callback)

Async function to read a single 4-byte word from memory.
The read operation happens without verifying that the addresses are accessible or even exist. The address parameter needs to be 32-bit aligned (must be a multiple of 4). Note that if the target address is in unpowered RAM, the operation will fail.
Please note that the data is a number - it is NOT a UInt32Array, and it is NOT a Buffer.
This is the same functionality as running "nrfjprog --memrd -w" in the command-line tools.

Source:

api.js, line 454

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to read memory from
`address`	`integer`	The address of the word to be read
`callback`	`function`	A callback function to handle the async response. It shall expect two parameters: (Error, integer).

Example

nrfjprogjs.read(123456789, 0, function(err, data) {
     if (err) throw err;
     console.log('The first word of memory looks like: ' + data);
});

(static) recover(serialNumber, progressCallbackopt, callback)

Async function to recover a device
This operation attempts to recover the device and leave it as it was when it left Nordic factory. It will attempt to connect, erase all user available flash, halt and eliminate any protection. Note that this operation may take up to 30 s if the device was readback protected. Note as well that this function only affects internal flash and CPU, but does not erase, reset or stop any peripheral, oscillator source nor extarnally QSPI-connected flash. The operation will therefore leave the watchdog still operational if it was running.
This is the same functionality as running "nrfjprog --recover" in the command-line tools.

Source:

api.js, line 605

Parameters:

Name	Type	Attributes	Description
`serialNumber`	`integer`		The serial number of the device to recover
`progressCallback`	`function`	<optional>	Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`		A callback function to handle the async response. It shall expect one parameter: (Error).

(static) verify(serialNumber, filename, options, progressCallbackopt, callback)

Async function to verify the program in the device
Compares the contents of the provided .hex file against the contents of the memory of the device connected.
This is the same functionality as running "nrfjprog --verify" in the command-line tools.

Source:

api.js, line 567

Parameters:

Name	Type	Attributes	Default	Description
`serialNumber`	`integer`			The serial number of the device
`filename`	`string`			The filename of the `.hex` file containing the program.
`options`	`Object`		{}	Reserved for future use.
`progressCallback`	`function`	<optional>		Optional parameter for getting progress callbacks. It shall expect one parameter: (Progress).
`callback`	`function`			A callback function to handle the async response. It shall expect one parameter: (Error).

Example

nrfjprogjs.verify(123456789, "/some/path/nrf52832_abcd.hex", function(err) {
     if (err) throw err;
});

(static) write(serialNumber, address, data, callback)

Async function to write data to a device's memory, given an array of byte values.
Please use an array of numbers - a UInt8Array might work due to type casting, but a Buffer will most likely fail.

Source:

api.js, line 624

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to write memory to
`address`	`integer`	The start address of the block of memory to be written
`data`	`Array.integer`	Array of byte values to be written
`callback`	`function`	A callback function to handle the async response It shall expect one parameter: (Error).

(static) writeU32(serialNumber, address, data, callback)

Async function to write data to a device's memory, given the value for a single 4-byte word.
Please use a single number as the parameter - do NOT use a UInt32Array or a Buffer.

Source:

api.js, line 643

Parameters:

Name	Type	Description
`serialNumber`	`integer`	The serial number of the device to write memory to
`address`	`integer`	Address of the memory word to be written
`data`	`integer`	Value to be written
`callback`	`function`	A callback function to handle the async response. It shall expect one parameter: (Error).

Type Definitions

DeviceInformation

Represents information of an individual device. The fields in this data structure about non-volatile memory, RAM, UICR and QSPI can also be found in the product specifications available at http://infocenter.nordicsemi.com, under the "Memory" section of each product model.

Properties:

Name	Type	Description
`family`	`integer`	Device family. Value will be equal to one of the following predefined constants: `nrfjprogjs.NRF51_FAMILY` `nrfjprogjs.NRF52_FAMILY` `nrfjprogjs.UNKNOWN_FAMILY`
`deviceType`	`integer`	Type of device. Value will be equal to one of the following predefined constants: `nrfjprogjs.NRF51xxx_xxAA_REV1` `nrfjprogjs.NRF51xxx_xxAA_REV2` `nrfjprogjs.NRF51xxx_xxAA_REV3` `nrfjprogjs.NRF51xxx_xxAB_REV3` `nrfjprogjs.NRF51xxx_xxAC_REV3` `nrfjprogjs.NRF51802_xxAA_REV3` `nrfjprogjs.NRF51801_xxAB_REV3` `nrfjprogjs.NRF52805_xxAA_REV1` `nrfjprogjs.NRF52805_xxAA_FUTURE` `nrfjprogjs.NRF52810_xxAA_REV1` `nrfjprogjs.NRF52810_xxAA_REV2<<` `nrfjprogjs.NRF52810_xxAA_FUTURE` `nrfjprogjs.NRF52811_xxAA_REV1` `nrfjprogjs.NRF52811_xxAA_FUTURE` `nrfjprogjs.NRF52832_xxAA_ENGA` `nrfjprogjs.NRF52832_xxAA_ENGB` `nrfjprogjs.NRF52832_xxAA_REV1` `nrfjprogjs.NRF52832_xxAA_REV2` `nrfjprogjs.NRF52832_xxAA_FUTURE` `nrfjprogjs.NRF52832_xxAB_REV1` `nrfjprogjs.NRF52832_xxAB_REV2` `nrfjprogjs.NRF52832_xxAB_FUTURE` `nrfjprogjs.NRF52833_xxAA_REV1` `nrfjprogjs.NRF52833_xxAA_FUTURE` `nrfjprogjs.NRF52840_xxAA_ENGA` `nrfjprogjs.NRF52840_xxAA_ENGB` `nrfjprogjs.NRF52840_xxAA_REV1` `nrfjprogjs.NRF52840_xxAA_REV2` `nrfjprogjs.NRF52840_xxAA_FUTURE` `nrfjprogjs.NRF9160_xxAA_REV1` `nrfjprogjs.NRF9160_xxAA_FUTURE`
`codeAddress`	`integer`	Memory address for the start of the non-volatile (flash) memory block. Typically `0x0000 0000`.
`codePageSize`	`integer`	Size of each page of non-volatile (flash) memory.
`codeSize`	`integer`	Total size of the non-volatile (flash) memory
`uicrAddress`	`integer`	Memory address for the start of the UICR (User Information Configuration Registers). Typically `0x1000 1000`.
`infoPageSize`	`integer`	Size of the FICR/UICR. Typically 4KiB.
`dataRamAddress`	`integer`	Memory address for the start of the volatile RAM. Typically `0x2000 0000`, in the SRAM memory region.
`ramSize`	`integer`	Size of the volatile RAM, in bytes.
`codeRamPresent`	`boolean`	Whether the volatile RAM is also mapped to a executable memory region or not.
`codeRamAddress`	`integer`	Memory address for the volatile RAM, in the code memory region. When `codeRamPresent` is true, both `codeRamAddress` and `dataRamAddress` point to the same volatile RAM, but the hardware uses a different data bus in each case.
`qspiPresent`	`boolean`	Whether QSPI (Quad Serial Peripheral Interface) is present or not.
`xipAddress`	`integer`	When `qspiPresent` is true, the memory address for the XIP (eXecute In Place) feature. This memory address maps to the external flash memory connected through QSPI.
`xipSize`	`integer`	Size of the XIP memory region.
`pinResetPin`	`integer`	Which pin acts as the reset pin. e.g. a value of `21` means that the pin marked as "P0.21" acts as the reset pin.

Source:

api.js, line 121

EraseOptions

Flags to be used when erasing a device.

Properties:

Name	Type	Default	Description
`erase_mode`	`integer`	nrfjporgjs.ERASE_ALL	How much of the memory should be erased. Value must be one of: `nrfjprogjs.ERASE_NONE` `nrfjprogjs.ERASE_ALL` `nrfjprogjs.ERASE_PAGES` `nrfjprogjs.ERASE_PAGES_INCLUDING_UICR`
`start_address`	`integer`	0	Start erasing from this address. Only relevant when using `ERASE_PAGES` or `ERASE_PAGES_INCLUDING_UICR` modes.
`end_address`	`integer`	0	Erasing up to this address. Only relevant when using `ERASE_PAGES` or `ERASE_PAGES_INCLUDING_UICR` modes.

Source:

api.js, line 274

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.CouldNotFindJlinkDLL` `nrfjprogjs.CouldNotFindJProgDLL` `nrfjprogjs.CouldNotOpenDevice` `nrfjprogjs.CouldNotOpenDLL` `nrfjprogjs.CouldNotConnectToDevice` `nrfjprogjs.CouldNotCallFunction` `nrfjprogjs.CouldNotErase` `nrfjprogjs.CouldNotProgram` `nrfjprogjs.CouldNotRead` `nrfjprogjs.CouldNotOpenHexFile`
`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:

api.js, line 61

Type:

Error

Examples

nrfprogjs.getLibraryVersion(function(err, version) {
    if (err) {
        throw err;
    } else {
        // success
    }
});

nrfprogjs.program(serialNumber, file, programmingOptions, function(err) {
    if (err && err.errno === nrfprogjs.CouldNotOpenHexFile) {
         console.error('.hex file not found');
    }
});

LibraryInformation

Represents the information about the J-link ARM interface library

Properties:

Properties

Name	Type	Description
`version`	`object`	The version of the interface library

Name	Type	Description
`major`	`integer`	The major version of the interface library
`minor`	`integer`	The minor version of the interface library
`revision`	`string`	The revision version of the interface library

path string The path to the interface library

Source:

api.js, line 217

ProbeInformation

Represents the device information of the debug probe

Properties:

Name	Type	Description
`serialNumber`	`integer`	The serialnumber of the probe
`clockSpeedkHz`	`integer`	The clock speed of the probe interface
`firmwareString`	`string`	The version infomation about the J-Link firmware

Source:

api.js, line 207

ProgramOptions

Option flags to be used when sending a program to the device.

Properties:

Name	Type	Default	Description
`inputFormat`	`integer`	nrfjprogjs.INPUT_FORMAT_HEX_FILE	How the `filename` string passed to `program()` shall be interpreted. Value must be one of: `nrfjprogjs.INPUT_FORMAT_HEX_FILE`: The string represents a filename for a .hex file `nrfjprogjs.INPUT_FORMAT_HEX_STRING`: The string represents the contents of a .hex file
`verify`	`boolean`	true	Whether verification should be performed as part of the programming. Akin to `nrfjprog --program --verify` in the command-line tools
`chip_erase_mode`	`integer`	nrfjprogjs.ERASE_ALL	How much of the flash memory should be erased. Value must be one of: `nrfjprogjs.ERASE_NONE` `nrfjprogjs.ERASE_ALL` `nrfjprogjs.ERASE_PAGES` `nrfjprogjs.ERASE_PAGES_INCLUDING_UICR`
`qspi_erase_mode`	`integer`	nrfjprogjs.ERASE_NONE	How much of the QSPI memory should be erased. Value must be one of: `nrfjprogjs.ERASE_NONE` `nrfjprogjs.ERASE_ALL` `nrfjprogjs.ERASE_PAGES` `nrfjprogjs.ERASE_PAGES_INCLUDING_UICR`
`reset`	`boolean`	true	Whether the device should be reset after programming.

Source:

api.js, line 239

Progress

Progress information.
Long running operations can indicate progress. If the optional progress callback is used, this object will be sent when progress is made.

Properties:

Name	Type	Description
`process`	`string`	An indication of what subprocess is performed.

Source:

api.js, line 104

ReadToFileOptions

Option flags to be used when reading the content of the device.

Properties:

Name	Type	Default	Description
`readram`	`boolean`	false	Read the contents of the ram
`readcode`	`boolean`	true	Read the contents of the flash
`readuicr`	`boolean`	false	Read the contents of the uicr
`readqspi`	`boolean`	false	Read the contents of the qspi

Source:

api.js, line 265

SerialNumberAndDeviceInformation

Represents the serial number and information of an individual device

Properties:

Name	Type	Description
`serialNumber`	`integer`
`deviceInfo`	`module:pc-nrfjprog-js~DeviceInformation`
`probeInfo`	`module:pc-nrfjprog-js~ProbeInformation`
`libraryInfo`	`module:pc-nrfjprog-js~LibraryInformation`

Source:

api.js, line 229

Version

Represents a semver-like version number, e.g. 9.6.0 as an object of the form { major: 9, minor: 6, revision: 0 }

Properties:

Name	Type	Description
`major`	`integer`	The major version number
`minor`	`integer`	The minor version number
`revision`	`integer`	The revision number

Source:

api.js, line 112