_____ _ | __|___ ___ ___ _ _|_|___ ___ | __|_ -| . | _| | | | | . | |_____|___| _|_| |___|_|_|_|___| |_|
As well as above, please see:
Please see the LICENSE file
Found a Bug?
Please check that:
- It hasn't already been found or been covered on our forum
- You're not just looking at outdated documentation (See the Building section to see how to build documentation)
Please submit bugs with clear steps to reproduce them (ideally a test case for the
tests directory), and if at all possible try and include a patch to fix them. Please be aware that we have a whole bunch of outstanding issues, so if you report something (especially if it doesn't contain a test or a pull request) it may not be fixed for quite some time.
Please see CONTRIBUTING.md
You can download binaries from http://www.espruino.com/Download (these aren't the latest, but are more likely to work with your board)
The only officially supported board is the Espruino Board. While Espruino can run on other boards, we make no money from them and so cannot afford to test, fix or support the firmware on them.
If you are a board manufacturer interested in getting your board officially supported, please Contact Us.
- Espruino Board - great support.
- Linux - WORKING
- STM32VLDISCOVERY - WORKING - limited memory so some features removed
- STM32F3DISCOVERY - setWatch is broken (issue #183)
- STM32F4DISCOVERY - WORKING
- STM32F401CDISCOVERY - appears WORKING, but very little testing done
- STM32F429IDISCOVERY - WORKING over serial (A9/A10). No USB and no LCD support
- HY STM32 2.4" - WORKING
- HY STM32 2.8" - WORKING - limited memory so some features removed
- HY STM32 3.2" - WORKING
- Olimexino - WORKING - limited memory so some features removed
- Carambola - WORKING - GPIO via filesystem (no SPI or I2C)
- Raspberry Pi - WORKING - GPIO via filesystem (no SPI or I2C)
- Sony SmartWatch - NOT WORKING - USB VCP support for F2 still needed
- MBed platforms - have not worked for a while - full hardware wrapper still required
- ARDUINOMEGA2560 - compiles, but has never worked. Almost certainly due to ints being 16 bits.
- LC-TECH STM32F103RBT6 - WORKING, but with some issues (LED inverted logic, BTN needs pullup to work)
- ST NUCLEO-F401RE - early alpha status
Building under Linux
Espruino is easy to build under Linux, and it is possible to build under MacOS with some effort. If you don't have Linux it's much easier to just use a Virtual Machine. See the heading Building under Windows/MacOS with a VM below for more information.
The (previously suggested) CodeSourcery GCC compiler is no longer available. We'd suggest you use gcc-arm-none-eabi.
Download the compiler, set up your path so you have access to it, and run:
YOUR_BOARD_NAME=1 RELEASE=1 make
- See the top of Makefile for board names
RELEASE=1, assertions are kept in the code (which is good for debugging, bad for performance + code size)
BOARDNAME=1 RELEASE=1 make serialflashwill flash to /dev/ttyUSB0 using the STM32 serial bootloader (what's needed for Espruino + HY boards)
BOARDNAME=1 RELEASE=1 make flashwill flash using st-flash if it's a discovery board, or the maple bootloader if using that 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
- Try different compilers.
codesourcery-2013.05-23-arm-none-eabiprovides low binary size for
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
ESPRUINO_1V3=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.
Building for Linux
Simple: Just run
Building for Arduino
This does not work right now - these steps are only to get you started!
sudo apt-get install gcc-avr avr-libc avrdude
sudo cp -r /usr/share/arduino/hardware/arduino targetlibs/arduino_avr
- You'll then need to flash the binary yourself
Building for Raspberry Pi
On the Pi, just run
Or to cross-compile:
cd targetlibs mkdir raspberrypi cd raspberrypi git clone git://github.com/raspberrypi/tools.git sudo apt-get install ia32-libs
Building for Carambola (OpenWRT)
To cross compile,
- Follow instructions at https://github.com/8devices/carambola to set toolchain up in
This will create a file called
Building under Windows/MacOS with a VM
- Download and install the correct VirtualBox for your platform. eg. If you have Windows, download 'VirtualBox for Windows Hosts'.
- Download the Ubuntu 14.04 32 bit Desktop ISO Image
- Run VirtualBox, and click the 'New' button
- Give the new OS a name, choose
Linuxas the type, and
Ubuntu (32 bit)as the version
Next, choose 2048MB of memory, and not to create a hard disk image (ignore the warning). Note: We're going to run Ubuntu right from the virtual CD without installing (because it's a bit faster and easier). If you have time you might want to create a hard disk image (you won't need as much memory then) and then choose to install Ubuntu when given the chance.
- Click start, and when prompted for a CD image choose the Ubuntu ISO you downloaded
- Wait until a picture of a keyboard appears at the bottom of the screen, then press enter
- Select a language, and then choose
Try Ubuntuwith the arrow keys
- When it's booted, press Alt-F2, type
gnome-terminal, then enter. Note: You could also just press Ctrl-Alt-F2 to get a faster but less shiny-looking terminal window.
- In the terminal, type:
sudo add-apt-repository ppa:terry.guo/gcc-arm-embeddedand press enter when prompted
sudo apt-get update
sudo apt-get install gcc-arm-none-eabi gitand press 'Y' if prompted
git clone https://github.com/espruino/Espruino.git
ESPRUINO_1V3=1 makeand wait
- Espruino is now built. See the documentation under Building under Linux for more examples.
- When you exit the VM, make sure you choose
Save State. If you
Power Offyou will lose everything you've done so far.
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 labelled
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 ESPRUINO_1V3=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.
There are a bunch of tests in the
tests directory. See
tests/README.md for examples on how to run them.
Directories and Files
ChangeLog: What's new
TODO: List of things to do
boards/: Information on boards, used to auto-generate a lot of the code
gen/: Auto-Generated Source Files
libs/: Optional libraries to include in Espruino (Math, Filesystem, Graphics, etc)
misc/: Other useful things
scripts/: Scripts for generating files in gen, and for analysing code/compilation/etc
src/: Main source code
targetlibs/: Libraries for targeted architectures
targets/: Specific code for targeted architectures
dist_*: files to be copied into distribution zip file
Adding more devices
Currently there are a bunch of different files to modify. Eventually the plan is to fit everything into boards/BOARDNAME.py and to auto-generate the rest of the config files.
- Most build options handled in
- Extra libraries like USB/LCD/filesystem in
boards/*.pyfiles describe the CPU, available pins, and connections - so the relevant linker script, headers + docs can be created
boards/pins/*.csvare copies of the 'pin definitions' table in the chip's datasheet. They are read in for STM32 chips by the
boards/*.pyfiles, but they are not required - see
boards/RASPBERRYPI.pyfor an example.
- Processor-specific code in
- Processor-specific libs in
src/jshardware.his effectively a simple abstraction layer for SPI/I2C/etc
- Create library functions (see examples in other jswrap files, also the comments in
Using Espruino in your Projects
If you're using Espruino for your own personal projects - go ahead, we hope you have fun - and please let us know what you do with it on http://www.espruino.com/Forum!
However if you're planning on selling the Espruino software on your own board, please talk to us:
- Read the terms of the MPLv2 Licence that Espruino is distributed under, and make sure you comply with it
- MPLv2 dictates that any files that you modify must be made available in source form. New files that you create don't need to be made available (although we'd encourage it!)
- You won't be able to call your board an 'Espruino' board unless it's agreed with us (we own the trademark)
- You must explain clearly in your documentation that your device uses Espruino internally
- If you're profiting from our hard work without contributing anything back, we're not going to very motivated to support you (or your users)