Skip to main content

Runtime Basics

This section covers how you interact with the runtime day to day: the REPL, modules, and filesystem behavior.

REPL commands​

CommandDescription
.helpShow available commands
.infoShow board info (chip, memory, filesystem)
.lsList files on the device
.cat FILEDisplay file contents
.rm FILEDelete a file
.run FILEExecute a JavaScript file
.multiline [FILE]Multi-line input (end with .end)
.formatFormat filesystem (prompted, 3s countdown)
.format!Format filesystem immediately
.uf2Reboot into UF2 mode (prompted)
.uf2!Reboot into UF2 mode immediately
.usbresetReset USB connection (reboot)

Quick REPL flow​

> .ls
index.js
lib/
> .cat index.js
const led = 25;
> .run index.js

If you want a quick refresher on REPL terms, check the Glossary.

Runtime JavaScript​

  • Console logging, timers, and globals are documented in Runtime JavaScript
  • Module APIs like fs, gpio, and neopixel live in Built-in Modules
  • NeoPixel is handy for boards with RGB LEDs
  • Use board.neopixel on boards with built-in NeoPixels (arrays or objects, missing values default to 0)
  • Multi-pixel arrays are truncated to board.neopixelLength
  • Object inputs are RGB; array inputs match the active neopixel.init() order
  • Array-of-objects stays RGB even when order is GRB
  • If you're just getting started, scan the examples below and then follow the links

Module loading​

  • Relative paths (./, ../) resolve from the current file
  • Absolute paths (/) resolve from the filesystem root
  • Bare imports resolve from /lib/ (create it if you want shared modules)
  • JSON files are parsed into objects
  • If you know CommonJS from Node, this will feel familiar

Example filesystem layout​

/
├── index.js
├── config.json
├── lib/
│   ├── math.js
│   └── blink.js
└── apps/
    └── status.js

Example imports​

// index.js
const fs = require('fs');
const math = require('math');
const blink = require('/lib/blink');
const status = require('./apps/status');
const config = require('./config.json');

const contents = fs.readFileSync('/apps/status.js');
console.log({ config, contentsLength: contents.length, sum: math.add(2, 3) });
blink.start(25);
status.report();

Filesystem behavior​

  • Files written by JavaScript persist immediately
  • Host OS directory caches can delay visibility of device-written files
  • If a file seems missing on your computer, unplug and replug the device

Key terms​