Repository files navigation

DAP.js is a JavaScript interface toCMSIS-DAP, enabling access to Arm Microcontrollers usingNode.js or in the browser usingWebUSB.

Node.js > v8.14.0, which includesnpm

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

$ npm install dapjs

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

The web examples can be seen running at:

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

Refer to theDAPjs API Documentation for more information.

Please refer to theWebUSB implementation status for browser support.

All transports outlined below are known to work on Windows 7, 8 and 10. Please refer to thenode-usb FAQ with any issues using theUSB orWebUSB transport inNode.js. TheHID transport is preferred on Windows.

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

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

Basic testing undertaken with no known issues. Please refer to thenode-usb FAQ with any issues using theUSB orWebUSB transport inNode.js.

All develoment boards supportingCMSIS-DAP should work. For the flash and serialDAPLink functionality, allMbed Enabled boards should work, but need the latestDAPLink firmware installed.

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

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

• Freedom K64F
• BBC micro:bit

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:

If you wish to use DAPjs in a browser environment, you must use WebUSB. Please refer to theimplementation 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 aWebUSB library exists to allow your program to be ported to Node.js.

To install the library for Node.js, use:

$ npm install webusb

In the browser, require the library:

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

In Node.js Require the libraries:

constusb=require('webusb').usb;constDAPjs=require('dapjs');

Then in either environment:

constdevice=await<navigator>.usb.requestDevice({filters:[{vendorId:0xD28}]});const transport = new DAPjs.WebUSB(device);const daplink = new DAPjs.DAPLink(transport);try{awaitdaplink.connect();awaitdaplink.disconnect();} catch(error){console.error(error.message||error);}

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

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

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

$ npm install node-hid

consthid=require('node-hid');constDAPjs=require('dapjs');letdevices=hid.devices();devices=devices.filter(device=>device.vendorId===0xD28);constdevice=newhid.HID(devices[0].path);consttransport=newDAPjs.HID(device);constdaplink=newDAPjs.DAPLink(transport);try{awaitdaplink.connect();awaitdaplink.disconnect();}catch(error){console.error(error.message||error);}

• Compatible with older CMSIS-DAP firmware.

• Requires HID access to JavaScript in your OS.

A "pure" USB transport exists which bypasses requiringWebUSB andHID.This utilises theusb library and is installed as follows:

$ npm install usb

constusb=require('usb');constDAPjs=require('dapjs');letdevices=usb.getDeviceList();devices=devices.filter(device=>device.deviceDescriptor.idVendor===0xD28);consttransport=newDAPjs.USB(devices[0]);constdaplink=newDAPjs.DAPLink(transport);try{awaitdaplink.connect();awaitdaplink.disconnect();}catch(error){console.error(error.message||error);}

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

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

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

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

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

TheProxy layer uses the transport layer to expose low-levelCMSIS-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.

• 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()

TheDAPLink layer is a special derived implementation of theCMSIS-DAP proxy implementation. It adds DAPLink vendor specific functionality such as Mass Storage Devicefirmware flashing andserial control.

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

• flash_progress
• serial_data

TheDAP (Debug Access Port) layer exposes low-level access to ports, registers and memory. An implementation exists forADI (Arm Debug Interface).

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

TheProcessor layer exposes access to the core processor registers.

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

After cloning this repository, install the development dependencies:

$ npm install

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

$ gulp$ gulp watch

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

$ npm run gulp$ npm run gulp watch

A localexpress server is included to run the web example locally:

$ node server.js

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

$ npm install ARMmbed/dapjs#gh-pages