DAP.js

DAP.js is a JavaScript interface to CMSIS-DAP, enabling access to Arm Microcontrollers using Node.js or in the browser using WebUSB.

Prerequisites

Node.js > v8.14.0, which includes npm

Installation

The package is distributed using npm. To install the package in your project:

$ npm install dapjs

Getting Started

Decide on a transport layer to use (see below) and refer to the examples folder to get started.

The web examples can be seen running at:

https://armmbed.github.io/dapjs/examples/index.html

Refer to the DAPjs API Documentation for more information.

Supported Systems

Browsers

Please refer to the WebUSB implementation status for browser support.

Windows

All transports outlined below are known to work on Windows 7, 8 and 10. Please refer to the node-usb FAQ with any issues using the USB or WebUSB transport in Node.js. The HID transport is preferred on Windows.

Please ensure you don't have the Mbed Serial driver installed on Windows 10 as this can cause issues and isn't needed on this platform.

MacOS

No known issues with any transports in Node.js Tested on MacOS 10.12.

Linux

Basic testing undertaken with no known issues. Please refer to the node-usb FAQ with any issues using the USB or WebUSB transport in Node.js.

Development Boards

All develoment boards supporting CMSIS-DAP should work. For the flash and serial DAPLink functionality, all Mbed Enabled boards should work, but need the latest DAPLink firmware installed.

The latest DAPLink containing WebUSB support needs to be built from the DAPLink source until we have prepared a new firmware release on https://armmbed.github.io/DAPLink/.

All examples have been tested with the latest DAPLink fiormware on the following hardware:

• Freedom K64F
• BBC micro:bit

Choosing a Transport

In order to use DAPjs, you need to install support for one of the transports. Use the following information to help you choose which to use:

WebUSB

If you wish to use DAPjs in a browser environment, you must use WebUSB. Please refer to the implementation status of WebUSB to understand browser support for this technology.

Note: WebUSB in the browser doesn't require any further libraries to be installed.

If you also want your program to work in a Node.js environment a WebUSB library exists to allow your program to be ported to Node.js.

To install the library for Node.js, use:

$ npm install webusb

Example

In the browser, require the library:

<script type="text/javascript" src="dist/dap.umd.js"></script>

In Node.js Require the libraries:

const usb = require('webusb').usb;
const DAPjs = require('dapjs');

Then in either environment:

const device = await <navigator>.usb.requestDevice({
    filters: [{vendorId: 0xD28}]
});

const transport = new DAPjs.WebUSB(device);
const daplink = new DAPjs.DAPLink(transport);

try {
    await daplink.connect();
    await daplink.disconnect();
} catch(error) {
    console.error(error.message || error);
}

Pros

• Works in the browser
• Programs are portable to Node.js environments

Cons

• Requires a recent version of DAPLink to be installed on your target device.

HID

For the highest level of firmware compatibility in a Node.js environment, the HID transport is recommended. This utilises the node-hid library and is installed as follows:

$ npm install node-hid

Example

const hid = require('node-hid');
const DAPjs = require('dapjs');

let devices = hid.devices();
devices = devices.filter(device => device.vendorId === 0xD28);

const device = new hid.HID(devices[0].path);
const transport = new DAPjs.HID(device);
const daplink = new DAPjs.DAPLink(transport);

try {
    await daplink.connect();
    await daplink.disconnect();
} catch(error) {
    console.error(error.message || error);
}

Pros

• Compatible with older CMSIS-DAP firmware.

Cons

• Requires HID access to JavaScript in your OS.

USB

A "pure" USB transport exists which bypasses requiring WebUSB and HID. This utilises the usb library and is installed as follows:

$ npm install usb

Example

const usb = require('usb');
const DAPjs = require('dapjs');

let devices = usb.getDeviceList();
devices = devices.filter(device => device.deviceDescriptor.idVendor === 0xD28);

const transport = new DAPjs.USB(devices[0]);
const daplink = new DAPjs.DAPLink(transport);

try {
    await daplink.connect();
    await daplink.disconnect();
} catch(error) {
    console.error(error.message || error);
}

Pros

• Doesn't require HID access to JavaScript in your OS.

Cons

• Requires a recent version of DAPLink to be installed on your target device.
• Can have issues on Windows machines

Architecture

The architecture of this project is built up in layers as follows:

Transport

The Transport layer offers access to the USB device plugged into the host. Different transports are available based on user needs (see above).

Implementation Status

• packetSize
• open()
• close()
• read()
• write()

Proxy

The Proxy layer uses the transport layer to expose low-level CMSIS-DAP commands to the next layer. A common use for the proxy is as a debug chip attached to the main processor accessed over USB.

A CMSIS-DAP implementation is included, however a network proxy or similar could be introduced at this layer in order to remote commands.

Implementation Status

• operationCount
• blockSize
• dapInfo()
• swjSequence()
• swjClock()
• transferConfigure()
• connect()
• disconnect()
• reconnect()
• reset()
• transfer()
• transferBlock()
• hostStatus()
• delay()
• writeAbort()
• swjPins()
• swdSequence()
• swdConfigure()
• swoTransport()
• swoMode()
• swoBaudrate()
• swoControl()
• swoStatus()
• swoExtendedStatus()
• swoData()
• jtagSequence()
• jtagConfigure()
• jtagIDCode()
• transferAbort()
• executeCommands()
• queueCommands()

DAPLink

The DAPLink layer is a special derived implementation of the CMSIS-DAP proxy implementation. It adds DAPLink vendor specific functionality such as Mass Storage Device firmware flashing and serial control.

Implementation Status

• flash()
• getSerialBaudrate()
• setSerialBaudrate()
• startSerialRead()
• stopSerialRead()
• serialWrite()

Events

• flash_progress
• serial_data

DAP

The DAP (Debug Access Port) layer exposes low-level access to ports, registers and memory. An implementation exists for ADI (Arm Debug Interface).

Implementation Status

• connect()
• disconnect()
• reconnect()
• reset()
• readDP()
• writeDP()
• readAP()
• writeAP()
• readMem8()
• writeMem8()
• readMem16()
• writeMem16()
• readMem32()
• writeMem32()
• readBlock()
• writeBlock()
• readBytes()
• writeBytes()

Processor

The Processor layer exposes access to the core processor registers.

Implementation Status

• getState()
• isHalted()
• halt()
• resume()
• readCoreRegister()
• readCoreRegisters()
• writeCoreRegister()
• execute()
• step()

Development

After cloning this repository, install the development dependencies:

$ npm install

Building

Gulp is used as a task runner to build the project. To build the project, simply run gulp or to continually build as source changes, run gulp watch:

$ gulp
$ gulp watch

A package.json script exists to run gulp if you don't have it installed globally:

$ npm run gulp
$ npm run gulp watch

Running

A local express server is included to run the web example locally:

$ node server.js

The latest build of master is always available to be installed from the gh-pages branch:

$ npm install ARMmbed/dapjs#gh-pages