_____ _ | __|___ ___ ___ _ _|_|___ ___ | __|_ -| . | _| | | | | . | |_____|___| _|_| |___|_|_|_|___| |_|
Espruino is a JavaScript interpreter for microcontrollers. It is designed to fit into devices with as little as 128kB Flash and 8kB RAM.
Please support Espruino by ordering one of our official boards.
It'd be best to browse the Espruino Website and read the FAQ first.
There's also a Reference for JavaScript commands as well as Tutorials. However please note that this repository is under heavy development, and the documentation on the Espruino website will match the version available for download but not the latest version on GitHub.
Builds for the Espruino Board (built automatically for each Git commit) are available from here
Other documentation of use is:
Please see the LICENSE file
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 with 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 - USB BROKEN
- 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 - beta status
- ST NUCLEO-F411RE - early alpha status
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 install it in a Virtual Machine. See the heading Building under Windows/MacOS with a VM below for more information.
Building for STM32 Boards (incl. Espruino Board)
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
- Without
RELEASE=1
, assertions are kept in the code (which is good for debugging, bad for performance + code size) BOARDNAME=1 RELEASE=1 make serialflash
will flash to /dev/ttyUSB0 using the STM32 serial bootloader (what's needed for the Espruino and HY boards)BOARDNAME=1 RELEASE=1 make flash
will flash using st-flash if it's a discovery board, the maple bootloader if using that board, or will copy the binary to/media/NUCLEO
if 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
TRAVIS=1
- Change the compile flags from
-O3
to-Os
in theMakefile
- Knock out some functionality (like
USE_GRAPHICS=1
) that you don't need in theMakefile
- Try different compilers.
codesourcery-2013.05-23-arm-none-eabi
provides low binary size for-O3
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 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.
Simple: Just run make
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
ARDUINOMEGA2560=1 make
- You'll then need to flash the binary yourself
On the Pi, just run make
.
Or to cross-compile:
cd targetlibs
mkdir raspberrypi
cd raspberrypi
git clone git://github.com/raspberrypi/tools.git
sudo apt-get install ia32-libs
To cross compile,
- Follow instructions at https://github.com/8devices/carambola to set toolchain up in
~/workspace/carambola
- Run
CARAMBOLA=1 make
python scripts/build_docs.py
This will create a file called functions.html
- Clone this repository.
- Download and install the correct VirtualBox for your platform. eg. If you have Windows, download 'VirtualBox for Windows Hosts'.
- Download and install the correct Vagrant for your platform.
If running on MacOS, the two previous steps can be accomplished easily with Homebrew Cask:
brew cask install virtualbox vagrant
will do it. - In your terminal application, navigate to your cloned working copy.
- Execute
vagrant up
. This will take a little while while the box is downloaded, and your virtual machine is provisioned. - When it is complete, execute
vagrant ssh
, which will open an ssh session into your new VM. - Execute
cd /vagrant && ESPRUINO_1V3=1 RELEASE=1 make
and wait. - Espruino is now built. See the documentation under Building under Linux for more examples.
- To terminate the ssh session, simply execute
exit
. vagrant suspend
will pause the VM,vagrant halt
will stop it, andvagrant up
will bring it back up again. See Vagrant's "Getting Started" page for further information.
- 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
Linux
as the type, andUbuntu (32 bit)
as the version - Click
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 Ubuntu
with 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-embedded
and press enter when prompted - Type
sudo apt-get update
- Type
sudo apt-get install gcc-arm-none-eabi git
and press 'Y' if prompted - Type
git clone https://github.com/espruino/Espruino.git
- Type
cd Espruino
- Type
ESPRUINO_1V3=1 RELEASE=1 make
and 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 youPower Off
you will lose everything you've done so far.
There's some more information on how to do this on the forum at http://forum.espruino.com/conversations/151 including links to a pre-made Amazon EC2 instance.
- 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 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.
There are a bunch of tests in the tests
directory. See tests/README.md
for examples on how to run them.
ChangeLog
: What's newTODO
: List of things to doboards/
: Information on boards, used to auto-generate a lot of the codegen/
: Auto-Generated Source Fileslibs/
: Optional libraries to include in Espruino (Math, Filesystem, Graphics, etc)misc/
: Other useful thingsscripts/
: Scripts for generating files in gen, and for analysing code/compilation/etcsrc/
: Main source codetargetlibs/
: Libraries for targeted architecturestargets/
: Specific code for targeted architecturestests/
: JavaScript Testcasesbenchmark/
: JavaScript Benchmarksdist_*
: files to be copied into distribution zip file
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
Makefile
- Extra libraries like USB/LCD/filesystem in
Makefile
boards/*.py
files describe the CPU, available pins, and connections - so the relevant linker script, headers + docs can be createdboards/pins/*.csv
are copies of the 'pin definitions' table in the chip's datasheet. They are read in for STM32 chips by theboards/*.py
files, but they are not required - seeboards/RASPBERRYPI.py
for an example.- Processor-specific code in
targets/ARCH
- eg.targets/stm32
,targets/linux
- Processor-specific libs in
targetlibs/foo
src/jshardware.h
is effectively a simple abstraction layer for SPI/I2C/etc
- Create
jswrap_mylib.c/h
inlibs/
- Create library functions (see examples in other jswrap files, also the comments in
scripts/common.py
)
See libs/README.md for a short tutorial on how to add your own libraries.
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)