There are several options to building Espruino on various platforms for the OS and board versions that are avaiable.
To build and run Espruino on the OS that one is using is as simple as the following, if prerequisits are met:
make clean && make
- In general, have a look through the Makefile to see what other options are available
- If you're swapping between compiling for different targets, you need to call
make cleanbefore you compile for the new target.
- If you have a ld error, check the board name in the BOARDNAME=1 make in the Makefile.
RELEASE=1for performance and code size, without it, assertions are kept for debugging.
Espruino is easy to build under Linux, for either for Espruino running on Linux or a board.
The current reference OS for building is Ubuntu 16.04.1 LTS, and the following can ensure problem free development:
Easy Method : provision.sh
Simply run the following with the name of your board to set your computer up ready for a build:
source scripts/provision.sh BOARDNAME
This should work for common platforms on Linux, but will only set paths up for your current session. You'll have to run it again next time you log in.
sudo apt-get update sudo apt-get install -y \ build-essential git python python-pip sudo pip install --upgrade pip # User choice for placement of source repos mkdir -p ~/source/repos/github/espruino cd ~/source/repos/github/espruino git clone https://github.com/espruino/Espruino.git cd Espruino make clean && make chmod +x espruino && sudo cp espruino /usr/local/bin
for an example of cross compilation for Puck.js
Having successfully created an native OS Espruino, try a cross compilation.
sudo apt-get update sudo pip install nrfutil sudo apt-get install -y \ lib32z1 lib32ncurses5 wget https://launchpad.net/gcc-arm-embedded/5.0/5-2016-q3-update/+download/gcc-arm-none-eabi-5_4-2016q3-20160926-linux.tar.bz2 tar xjf gcc-arm-none-eabi-5_4-2016q3-20160926-linux.tar.bz2 sudo mv gcc-arm-none-eabi-5_4-2016q3-20160926 /usr/local export PATH=/usr/local/gcc-arm-none-eabi-5_4-2016q3/bin:$PATH cd ~/source/repos/github/espruino/Espruino make clean && DFU_UPDATE_BUILD=1 BOARD=PUCKJS RELEASE=1 make ls -l *puckjs*
- It is possible to build Espruino under MacOS with some effort.
- PR for an easy Espruino build under MacOS are welcome.
- If you don't have Linux it's much easier to install it in a Virtual Machine (see below).
It is possible to build Espruino under Windows with the following addition to the Linux explanation:
- Install Bash on Ubuntu on Windows 10 https://msdn.microsoft.com/da-dk/commandline/wsl/install_guide
- After enabling, just use the instructions for Linux
- there is no access to USB in the present version
- copy any crosscompile output to one's user directory and either bluetooth or USB the result to the target
- Ubuntu 14.04 LTS is the present version.
Or use a Virtual machine as described below dependent on ones taste.
for Raspberry Pi
Using RASPBIAN JESSIE WITH PIXEL, getting Espruino is easy.
To enable the full power of Espruino on the Pi, WiringPi:
sudo apt-get install wiringpi
- clone this repository and cd into the directory
make clean && make
chmod +x espruino && sudo cp espruino /usr/local/bin
Follow the instructions for OpenWRT build system
After a successful OpenWRT build, OpenWRT Espruino packages
make clean && BOARD=BOARDNAME RELEASE=1 make
Where BOARDNAME is one of:
PICO_R1_3for Espruino Pico
ESPRUINOBOARDfor Original Espruino
ESPRUINOWIFIfor Espruino WiFi
Or choose another board name based on the files in
BOARD=BOARDNAME RELEASE=1 make serialflashwill flash to /dev/ttyUSB0 using the STM32 serial bootloader (what's needed for the Espruino and HY boards)
BOARD=BOARDNAME RELEASE=1 make flashwill flash using st-flash if it's a discovery board, the maple bootloader if using that board, or will copy the binary to
/media/NUCLEOif using a Nucleo board.
It may complain that there isn't enough space on the chip. This isn't an issue unless you save to flash, but you can fix the error in a few ways:
- Disable the check by adding
- Change the compile flags from
- Knock out some functionality (like
USE_GRAPHICS=1) that you don't need in the
Note: Espruino boards contain a special bootloader at
0x08000000 (the default address), with the Espruino binary moved on 10240 bytes to
0x08002800. To load the Espruino binary onto a board at the correct address, use
BOARD=ESPRUINO_1V3 RELEASE=1 make serialflash. If you want to make a binary that contains the bootloader as well as Espruino (like the ones that the Espruino Web IDE expects to use) use the script
scripts/create_espruino_image_1v3.sh which will compile the bootloader and Espruino, and then join them together.
Dependant on the board, either usb or bluetooth can be used to program the board or install the bootloader from different devices.
- Bluetooth Low energy
- the board will appear as
XYZis the board name
- the board will appear as
- the board appears as a drive to drop a hex on
The Puck.js is based on the nRF52
make clean && DFU_UPDATE_BUILD=1 BOARD=PUCKJS RELEASE=1 make
The resulting file is a zip that has to be transferred to the puck.js via a Bluetooth low energy device. See https://www.espruino.com/Puck.js+Quick+Start for information concerning transferring the zip to the puck.js.
All boards based on the nRF52 have RAM and Flash to support Espruino without feature disablement.
make clean && BOARD=NRF52832DK RELEASE=1 make
The micro:bit is based on the nRF51.
make clean && BOARD=MICROBIT RELEASE=1 make
- Drop the hex generated on the micro:bit drive and it is then an Espruino.
- At the time of writing, if one uses the Espruino Web IDE, access the Settings->Communications
- Request board details on connect: false
- Throttle Send: true
All boards based on the nRF51 are limited in RAM and Flash so many features are disabled.
make clean && BOARD=NRF51822DK RELEASE=1 make
In order to compile for the esp8266 on Linux several pre-requisites have to be installed:
- the esp-open-sdk from https://github.com/pfalcon/esp-open-sdk, use make STANDALONE=n
- the Espressif SDK (version 1.5.0 with lwip patch as of this writing) from http://bbs.espressif.com/viewforum.php?f=46 and http://bbs.espressif.com/viewtopic.php?f=7&t=1528
To run make you need to pass a couple of environment variables to
make. These include:
FLASH_4MB=1if you have an esp-12
ESP8266_SDK_ROOT=<Path to the 1.4 SDK>
PATH=<Path to esp-open-sdk/xtensa-lx106-elf/bin/>
The easiest is to place the following lines into a script, adapt it to your needs and then run it.
#! /bin/bash export BOARD=ESP8266_BOARD export FLASH_4MB=1 export ESP8266_SDK_ROOT=/esp8266/esp_iot_sdk_v1.5.0 export PATH=$PATH:/esp8266/esp-open-sdk/xtensa-lx106-elf/bin/ export COMPORT=/dev/ttyUSB0 make clean && make $*
- If you do
make flashit will try to flash your esp8266 module over serial
- If you do
make wiflashit will try to flash you esp8266 module over wifi, which assumes that it's already running Espruino
- You will also get an
espruino_1v00_*_esp8266.tgzarchive, which contains everything you need to flash a module (except for esptool.py), including a README_flash.txt
On 64 bit linux:
git clone https://github.com/espruino/Espruino.git cd Espruino source scripts/provision.sh ESP32 make clean && BOARD=ESP32 make
If you are on a different platform such as the Mac, you will need to install the toolchain and esp-idf for your platform, see http://esp-idf.readthedocs.io/en/latest/macos-setup.html
The easiest way to get the esp-idf environment is to install: https://github.com/espruino/EspruinoBuildTools
and then replace the toolchain with what is required for your platform.
You only need to use the EspruinoBuildTools if you want to compile esp-idf libaries
Building on Eclipse
When building on Eclipse, update the Makefile properties to include the definitions show above. The easiest way to achieve
that task is to right-click your Espruino project and select
properties. From there, navigate to
C/C++ Build > Environment.
Note: the emw3165 port is very preliminary and does not include Wifi support at this time. The text below is what is planned in order to support Wifi, but it doesn't exist yet.
The EMW3165 port uses WICED, which is an application framework provided by Broadcom for its wifi chips, such as the BCM43362 used in the EMW3165 module. The module consists of an STM32F411CE processor and the BCM43362. The WICED framework comes with everything and the kitchen sink plus a rather complex build process in order to support umpteen different processor and wifi chip combinations, plus various use-cases. WICED includes FreeRTOS and LwIP plus proprietary code to manage the Wifi chip.
The strategy employed is to compile portions of WICED into a library using the WICED toolchain and then linking this into Espruino.
Setting up WICED:
- WICED does not officially support the EMW3165.
- Clone https://github.com/MXCHIP-EMW/WICED-for-EMW and follow the instructions there to configure WICED and build it. (You will need to sign up for a developer acct with Broadcom.)
- Build the apsta sample program (snippet) using a command-line like
./make EMW3165-FreeRTOS-LwIP-snip.apsta download run JTAG=stlink-v2
- Hook up your emw3165 to an ST-Link-v2 or your preferred STM32 programmer and flash using the above command-line. You should see the EMW's access point.
- An alternative program to test with is the "scan" snip as it will also print something on the
console (works well with the WifiMCU board):
./make EMW3165-FreeRTOS-LwIP-snip.scan ...
Compiling WICED into a library:
- ... if only this worked ...
- To compile Espruino you will need to point to the WICED root and include files. This is done by specifying a WICED_ROOT environment variable.
- Adapt the pathnames from the following script:
WICED_ROOT=/home/emw3165/WICED-for-EMW/WICED-SDK-3.3.1 make $*
sudo pip install markdown python scripts/build_docs.py
This will create a file called
functions.html that is a version of the reference pages,
but based on your source code.
Virtual Machines under Windows and MacOS
- Installation of https://git-scm.com/ gives a ssh that can be used with vagrant ssh
Vagrant and VirtualBox
- For your host OS (Windows or MacOS)
- Clone this repository and navigate with the command prompt to the contents
- Install the auto-network plugin
vagrant plugin install vagrant-auto_network
- This will take a little while while the box is downloaded, and your virtual machine is provisioned.
- a ssh session into your new VM will be created.
cd /vagrant && make clean && make
- a native OS version of Espruino is now built. See this documentation for further examples
- To exit the ssh session
- On the host OS, the following are useful vagrant commands
- will pause the VM
- will stop the VM
- See Vagrant's "Getting Started" page for further information.
If one does not wish to use vagrant, then install Virtual Box and use the Linux method.
In order to access USB, bluetooth or connected USB devices, one has USB filters to dedicate access to the guest OS. The easiest method is via the VirtualBox Manager, and select which devices should be dedicated to the VM with the device filter. Note: VirtualBox Guest Additions from VirtualBox are required.
To flash Espruino from the VM
- Plug the Espruino board in while holding BTN1, and wait for Windows to finish connecting to the USB device
- Go into the VirtualBox Manager (There's no need to stop your VM)
- Click on
USB, then click on the icon with the
+sign (With the tooltip 'Adds a new USB filter ... selected USB device')
- Click on the device labeled
STMicroelectronics STM32 ...
- Now unplug the Espruino board, wait a few seconds, and plug it back in (holding BTN1 again)
- Go back into the VM, and type
sudo BOARD=ESPRUINO_1V3 RELEASE=1 make serialflash
- Your board will now be flashed
Note: if you want to you can change permissions so you don't need
sudo by typing
sudo cp misc/45-espruino.rules /etc/udev/rules.d;sudo udevadm control --reload-rules and then re-inserting the board.