Modules

In Espruino, Modules are pieces of pre-written code that perform common tasks, such as interfacing to different bits of hardware. On this site we generally mean the same thing when referring to "modules" or "libraries".

They can either be JS modules that are loaded from the internet on demand, or they may come compiled in to the Espruino firmware itself.

• Working with Modules
• Built-in modules
• Espruino Modules
• from Github (or anywhere on the internet)
• from Storage
• from NPM
• from a local folder
• from SD card
• from the Internet
• Existing Modules
• Built-in Functionality
• Frequently Asked Questions
• Why don't modules work when typing require on the left-hand side of the Web IDE (or from a terminal window)?
• If I load modules from an SD card, will the SD card always need to be inserted?
• Can I dynamically load (and unload) modules?
• How do I make my own modules?

Working with Modules

Note: Module names are case sensitive. For example require("WiFi") and require("Wifi") do not do the same thing.

If you're using the Espruino Web IDE or Espruino command-line tools, simply write require("modulename") on the right-hand side. When you click the Send to Espruino button, the Web IDE (or command line tools) will automatically look online for minified versions of the modules you need, download them, and load them onto the board. You don't need an SD card or an internet connection to the Espruino board itself.

Note: The left-hand side of the IDE is a direct connection to the board itself, which the IDE does not interfere with. As such, if you type require("modulename") in the left-hand side then the IDE will not have a chance to dynamically load the module for you, so if it's not in Espruino you won't be able to use it. To fix that, just add require("modulename") to the right-hand side of the IDE (nothing else is required) and click Send to Espruino - the IDE will then upload that module and you'll be able to use it from the left-hand side.

Built-in modules

Some modules come built-in to the Espruino firmware on certain boards. If this is the case then the Web IDE won't attempt to load the module and the built-in one will be used.

You can check which modules your board has just connecting to it with the Web IDE, then clicking the Settings icon in the Web IDE, going to Board Information and looking at MODULES (the same info is available by typing process.env.MODULES too).

You can find more information on most of them via Espruino's Software Reference

If the Web IDE says Module not found when trying to upload a module that you know exists on your board, try reconnecting the IDE. If the IDE fails to communicate with the board when it first connects, it will be unable to get a list of the preinstalled modules and so will assume the module has to be downloaded (many pre-installed modules do not have downloadable equivalents).

Espruino Modules

If you are using the Web IDE or command-line tools as is, the modules will be loaded from http://www.espruino.com/modules/ (which is a curated set of modules in https://github.com/espruino/EspruinoDocs). This URL can be changed in Web IDE settings.

To save space, most modules are provided as a minified version and the Web IDE tries to load minified versions first with default configuration (this can be changed in Settings -> Communications -> Module Extensions).

For example, using require("ADNS5050"); will make the Web IDE load the minified module from http://www.espruino.com/modules/ADNS5050.min.js.

If you need to use modules while not connected to the internet, Settings -> Offline Mode allows you to download all available modules for offline use.

from Github (or anywhere on the internet)

You can type a URL into require, so you can actually just pull a module right off GitHub:

require("https://github.com/espruino/EspruinoDocs/blob/master/devices/PCD8544.js");

You can even look at the history of something on GitHub, and can then require a specific version of that file with:

require("https://github.com/espruino/EspruinoDocs/blob/d4996cb3179abe260c030ed02bcb0d2384db6bbd/devices/PCD8544.js");

The URL comes from clicking <> by the commit you were interested in in GitHub.

Note: You can use any URL, however because the Web IDE runs in a browser, the server that you access files from must have Cross Origin Resource Sharing (CORS) headers enabled.

from Storage

On Espruino 2v00 and above on devices with enough memory you can write a module to Espruino's flash memory using the built-in Storage module. It'll then be loaded automatically by Espruino:

require("Storage").write("answer",`
exports.get = function() {
  return 42;
};`)
print(require("answer").get());
// prints 42

Note:

• Modules written to Espruino's flash memory can only have names that are a maximum of 8 characters long.
• If you are adding a module using a Templated String (as in the example above) be aware that escape characters inside strings need double-escaping - eg. "\n" must become "\\n". To avoid doing this manually you can use the Espruino File Converter page.
• The Espruino Web IDE and Command-line tools will be unaware of extra modules in Storage. When uploading code they may attempt to find the module online and re-upload it, or complain that the module is not found. Make sure there isn't a module of the same name in http://www.espruino.com/modules/

from NPM

There was a beta option in Web IDE to load modules from the NPM repository. After some testing it was removed (The vast majority of NPM modules are just too large to fit in a microcontroller with their dependencies).

If you require NPM modules we'd recommend that you use a tree-shaking/bundling system like rollup to bundle your NPM modules into one file, and then use the Espruino command-line tools to upload it.

from a local folder

If you set a project folder with Web IDE -> Settings -> Project, the Web IDE will automatically create an empty modules folder inside it. Put a module there and you can load it with require("myCustomModule");.

Note: This feature is not currently implemented in the 'Web App' IDE available at https://www.espruino.com/ide/. You'll need to use the Native versions

With default Web IDE configuration, it will look for modules following this order:

1. local minified
2. online minified
3. local normal
4. online normal

If your own module has the same name as one of the existing ones, the Web IDE will use the minified version from online first.

If you need it anyway, you can provide a local minified version or you can change the Web IDE configuration from .min.js|.js to .js|.min.js or even myCustomModule.js|.min.js|.js to get it working.

Note: When the Web IDE is running in the browser it cannot access any folders on your local computer, so the Projects functionality is disabled.

from SD card

If you have an Espruino with an SD card (but you're not using the Web IDE), you can copy the modules you need into a directory called 'node_modules' on the SD card. Now, whenever you write require("modulename") the module will be used.

If you don't have an SD card, see Modules from Storage above.

from the Internet

The Web IDE or command-line tools will load modules from the internet automatically when you upload - see Espruino modules above.

However an Internet-connected Espruino device can't automatically load a modules from the internet by itself because require is synchronous while network connections are asynchronous.

However you can use the following asyncronous code to load a module from the internet on demand.

function loadModule(moduleName, callback) {
  require("http").get("http://www.espruino.com/modules/"+moduleName+".min.js", function(res) {
    var contents = "";
    res.on('data', function(data) { contents += data; });
    res.on('close', function() {
      Modules.addCached(moduleName, contents);
      if (callback) callback();
    });
  }).on('error', function(e) {
    console.log("ERROR", e);
  });
}

// for example:
loadModule("PCD8544", function() { // loads PCD8544.min.js
  SPI1.setup({ sck:B3, mosi:B5 });
  var g = require("PCD8544").connect(SPI1, B6 /*DC*/, B7 /*CE*/, B8 /*RST*/, function() {
    ...
  });
});

Existing Modules

These are the existing modules that are available for download to Espruino:

Graph Library Bluetooth LE Emoji Advertising LEGO Power Functions Clone Remote Control (Mould King M-0006 / Kaiyu / Bandra / AKOGD / MayD / etc) W25Qxx and W25Xxx Serial NOR Flash BTHome Library nRF52 Low Level Interface Library Renesas FS3000 Air velocity sensor module Bluetooth LE UARTs (NUS) SSD16XX e-Paper display driver Fonts Arduino Pico adaptor board Bluetooth LE HID Keyboards 433.92Mhz Transmitter and Receiver ST7735 LCD controller Bluetooth LE MIDI PMS7003 Particulate matter sensor Quectel LTE BG96 Cat.M1/NB1 & EGPRS Module AHT10 RH/TEMP Sensor Averager Library BH1792 I2C Heart rate Sensor Seeed Wio LTE TMP117 Temperature Sensor MLX90632 non-contact temperature sensor Ruuvitag MAX30102 Heart rate monitor HD44780 Character LCD INA226 Current/Voltage Measurement IC INA219 Zero-Drift, Bidirectional Current/Power Monitor With I2C Interface Midi ST7789 LCD controller ILI9341 LCD controller iBeacons Eddystone Beacons UI radio button module UI Checkbox module Smartibot REYAX RYLR896/406/895/405 LoRa modules SSD1306 OLED driver VL53L1X SSD1606 e-Paper display driver Bluetooth LE Printers Bluetooth LE HTTP Proxies PCD8544 LCD driver (Nokia 5110) ADNS5050 Optical Mouse Sensor DS18B20 Temperature Sensor SH1106 OLED driver GPS Module WebSockets Quectel M35 Quad-band GSM/GPRS module Module SMS Send and Receive PN532 NFC/RFID module Futaba S.Bus System DHT22/AM230x/RHT0x Temperature and RH Sensor MFRC522 NFC/RFID module MS5803 Pressure Sensor MAX7219 7 segment display driver Infrared 'Pronto Hex' decoder NRF24L01+ Wireless Module SeeedStudio Grove System VT100 Terminal Emulator MAX6675 Thermocouple Controller VL53L0X Writing and Submitting Modules (or changes) Wii Nunchuck SSD1351 OLED display driver CMUcam5 Pixy MQ135 Air Quality Sensor MLX90614 Infra Red thermometer Sharp Memory LCD MAG3110 3-axis magnetometer LPD-6416 LED Matrix Display KeyPad Matrix Infrared Remote Control Receiver Module ILI9163 LCD controller HP03S pressure sensor module HC-SR04 Ultrasonic Distance Sensor LPRS easyRadio (eRIC) Radio Modules DCF77 Espruino Parallel to Serial Shifting-In with a CD4021BE PID Controller LED BLE Library HMAC Module AbortController for Espruino DMX SSD1327 OLED driver MMC212xMG Dual-axis Magnetic Sensor from MEMSIC used in HDMM01 breakout from Pollin HX711 24-Bit ADC for Scales MAX1704x Battery Fuel Gauge ADS1x15 programmable gain ADC DRV2605 Module for the MPR121 12-Channel Capacitive Sensor (I2C) Graphical Menu MCP794xx Battery-Backed I2C Real-Time Clock/Calendar with SRAM, (optional) EEPROM and Protected EEPROM MQTT Client DS3231 RTC SHT4x Temperature and Humidity sensor Local Date Extensions String Decoders SX1276/77/78/79 LoRa Modules AT Command Handler EEPROM on Flash LIS3DH Accelerometer BH1750 I2C Light Sensor Analog RGB LED Control MCP4xxx0 SPI digital potentiometers Time-based One-time Password Base 32 Decoder SHT3C Temperature and Humidity sensor Sensirion SHT20, SHT21 & SHT25 Temperature and Relative Humidity Sensor OPT3001 Light Sensor LPS22HB pressure sensor TLE94112 ST7565/ST7567 128x64 Monochrome LCD driver UI input field module UI slider module UI Framework for microcontrollers UI extension for button control vs touch screen control UI Button module XPT2046 MAX44009 I2C Ambient Light Sensor CCS811 Digital Air Quality Sensor AT25xxx SPI EEPROMs (incl. M95xxx, 25AAxxx, 25LCxxx, CAT25xxx, BR25Sxxx) AT24Cxxx I2C EEPROM and FRAM (incl. M24M02, MB85RCxx, FT24Cxxx, 24LCxxx, CAT24Cxxx, BR24Gxxx) BME280 Environment sensor Tiny MQTT Client (tinyMQTT) PCA9685 Port Expander IS31FL3731 Charlieplexed LED controller APDS9960 Light and gesture sensor SH1107 OLED driver BME680 Environment sensor MPU9250 accelerometer/gyro/magnetometer SNTP Module SIMCom SIM800/SIM900 GSM/GPRS Module Simple Linux-like Cron system RN2483/RN2483A LoRa Modules nRF52 Accurate Stepper Motor Driver LIS2MDL Magnetometer Bluefruit LE app interface Quectel UG9x GSM/GPRS/EDGE and UMTS/HSPA Module TM1640 8x8 Matrix LED Shield driver TSL2561 Luminosity sensor TCS3472x I2C Color Sensor TCS3200 Light Sensor SI7021(-A20) I2C Temperature and Humidity Sensor LSM6DSL Accelerometer and 3D Gyroscope LIS2DH12 Accelerometer Bitmap file (BMP) Loader Module HTU21D Temperature and RH Sensor BH1745 Digital Color Sensor HTS221 humidity and temperature sensor DS2xxx OneWire EEPROMs (DS24B33, DS2431, DS28EC20 etc) BMP280 Environment sensor Espruino InfluxDB module Vec3 - 3 element Vector Ping Espruino WebServer Module Vizibles Vizibles (Español) Simple Finite State Machine MySensors Client/Gateway Losant InitialState Date Module Clock Module xBee radio module Touchscreen Thermistor Temperature Sensor STM32F1 Flash Memory Module SmartNixie Nixie Tube driver Sensirion SHT10 SHT11 & SHT15 Temperature and Relative Humidity Sensor Module HopeRF RFM69 Wireless Module nRF905 Wireless Transceiver MPU6050 accelerometer and gyro MPL3115A2 Digital Altitude / Pressure / Temperature Sensor MPL115A2, I2C digital barometer and temperature sensor MCP9808 precision I2C temperature sensor MCP4xxx I2C and SPI digital potentiometers MCP23xxx I2C and SPI port expanders MAX31855 Thermocouple Controller LPS25HB pressure sensor HMC5883 Compass/Magnetometer Rotary Encoder EasyVR Voice Recognition Board Digole LCD driver (monochrome) DHT11 Temperature and RH Sensor Charlieplexed LED Module CAP1188 capacitive touch breakout NeuroSky ThinkGear ASIC module BMP085/BMP180 digital pressure sensor ADXL345 Accelerometer ADXL335 Accelerometer ADS7843 Touchscreen

Built-in Functionality

Espruino also contains many built-in modules and classes that provide a lot of functionality - these are some of them:

Graphics Library Inline Assembler Waveforms Espruino Performance Notes ESP8266 WiFi Module JIT Compiler Saving code on Espruino JavaScript Compilation Servo Motors CC3000 WiFi Module WIZnet WIZ550io/W5500 Ethernet module Internet (HTTP/TCP/UDP/etc) USART / UART / Serial Port WS2811/WS2812/WS2812B/APA104/APA106/SK6812 LED String/Strip Inline C code SPI - Serial Peripheral Interface Pulse Width Modulation OneWire I2C - Inter-Integrated Circuit Digital to Analog Converter Analog IO Analog to Digital Converter Bluetooth

You don't need a module to be able to interface to hardware - sometimes it just makes it easier. If you want to interface to a device that isn't listed here, please check out the Tutorials page, or Search for it.

Frequently Asked Questions

Why don't modules work when typing require on the left-hand side of the Web IDE (or from a terminal window)?

When you type require("modulename") on the right-hand side and click Send to Espruino, the Espruino Web IDE scans your code for require statements and loads the relevant modules off the internet. Because the left-hand side of the Web IDE (or a terminal window) sends each character direct to Espruino, by the time you have pressed enter to execute your command, it's then too late to load the module.

Instead, Espruino defaults to what is mentioned under the Stand-alone Espruino heading above - it looks on an SD card (if inserted) for the module. This is why you might get a ERROR: Unable to read file : NOT_READY error written to the console.

If I load modules from an SD card, will the SD card always need to be inserted?

No. As long as you have used require('module') at least once for each module before you type save(), all the information that is needed will be cached inside Espruino.

Can I dynamically load (and unload) modules?

Yes. By default each module that is loaded will be cached (to avoid loading modules twice). However you can call Modules.removeCached('modulename') which will remove the module from the cache and free the memory that it uses.

How do I make my own modules?

It's easy! See the Writing Modules page...