espruino/espruinobuildtools

Build tools needed to build Espruino on embedded platforms

Espruino JavaScript for Microcontrollers

 _____                 _
|   __|___ ___ ___ _ _|_|___ ___
|   __|_ -| . |  _| | | |   | . |
|_____|___|  _|_| |___|_|_|_|___|
          |_|

https://www.espruino.com          

About

Espruino is a JavaScript interpreter for microcontrollers. It is designed for devices with as little as 128kB Flash and 8kB RAM.

Please support Espruino by ordering one of our official boards or donating.

Documentation

If you have an Espruino board, please read the Quick Start Guide first.

Browse the Espruino Website (try using search in the top right), and read the FAQ.

There's also a Reference for JavaScript commands as well as Tutorials. However 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 and Pico Board (built automatically for each Git commit) are available from here.

Other documentation of use is:

• The Forum
• FAQ
• Troubleshooting
• Performance Notes
• Implementation Notes
• Build Process Notes
• Building Espruino
• Making your own libraries
• Hardware Debugging Notes

Support / Bugs

First, please try and check that your problem hasn't already been found or covered on our forum.

Submit bugs with clear steps to reproduce them: a small test case (not your whole program), and an actual and expected result. If you can't come up with these, please post on the forum first as it may just be something in your code that we can help out with.

Work on Espruino is supported by sales of our boards.

If your board isn't made by us but came pre-installed with Espruino then you should contact the manufacturers.

We try and support users of the boards we sell, but if you bought a non-official board your issue may not get addressed. In this case, please consider donating to help cover the time it takes to fix problems (even so, we can't guarantee to fix every problem).

License

Please see the LICENSE file.

Building

Check out the page on building Espruino.

Testing

There are a bunch of tests in the tests directory. See tests/README.md for examples on how to run them.

Current State

The officially supported boards are the best supported. They come pre-installed with Espruino and you are able to easily download and flash the latest versions of Espruino to them.

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. We're dependent on the community.

You can download binaries from https://www.espruino.com/Download.

If you are a board manufacturer interested in getting your board officially supported, please check out this page.

For a list of supported boards, please see the boards folder.

Main supported platforms are:

• STM32 (F1, F3, F4, L4)
• nRF52
• nRF51
• ESP8266
• ESP32
• Linux

Espruino has been ported to other boards and platforms (such as EFM32 and SAMD), but these have a habit of being contributed and then never maintained. All boards that this has happened to reside in the UNMAINTAINED_BOARDS branch.

Modification

Check out the documentation on the build process first - this should clear up a lot of potential questions about the Espruino architecture.

Please see CONTRIBUTING.md for some hints about code style/etc.

You can auto-build documentation for all source files - see doxygen/README.md

Any more questions? ask on the forum.

Porting to new devices

If you're using an existing architecture everything can be done from boards/BOARDNAME.py. See a similar board's .py file as an example.

However for a new architecture there are a bunch of different files to modify.

• boards/*.py files describe the CPU, available pins, and connections - so the relevant linker script, headers + docs can be created
• boards/pins/*.csv are copies of the 'pin definitions' table in the chip's datasheet. They are read in for STM32 chips by the boards/*.py files, but they are not required - see boards/MICROBIT.py for an example.
• Global build options are handled in Makefile
• The make directory contains arch-specific Makefile fragments
• Extra libraries like USB/LCD/filesystem are in Makefile
• Processor-specific code in targets/ARCH - eg. targets/stm32, targets/linux
• Processor-specific libs (like the SDK) in targetlibs/ARCH
• src/jshardware.h is effectively a simple abstraction layer for SPI/I2C/etc, which should be implemented in targets/ARCH/jshardware.c

Adding libraries

• Create jswrap_mylib.c/h in libs/
• 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.

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 https://www.espruino.com/Forum!

If you're planning on selling the Espruino software on your own board, please:

• Let us know, we might be able to help.
• 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
• Please don't fork Espruino - improvements get very hard to share, and in the long run everyone loses.
• Please give something back to the project - be it code improvements, documentation or support.

We spend a lot of time supporting Espruino on the forums, but can only do so because we make money from the sales of Espruino boards. If your users request support from us then we have absolutely no obligation to help them. However, we'll be a lot more motivated if you're actively helping to improve Espruino for all its users (not just your own).

espruinobuildtools's Issues

Building esp-idf for ESP32

Hi @MaBecker,

Using the instructions at https://github.com/espruino/EspruinoBuildTools/tree/master/esp32 I did the following:

$ source build-idf.sh 

using esp-idf branch v3.3.6, espruino branch master, checkout mode none
Provision BOARDNAME = ESP32
Provision FAMILY = ESP32
===== ESP32
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)
python/pip installed
pyserial installed
ESP_IDF_PATH=/home/gw/workspace/EspruinoBuildTools/esp32/build/Espruino/esp-idf
ESP_APP_TEMPLATE_PATH=/home/gw/workspace/EspruinoBuildTools/esp32/build/Espruino/app
PATH=$PATH:/home/gw/workspace/EspruinoBuildTools/esp32/build/Espruino/xtensa-esp32-elf/bin/
GCC is /home/gw/workspace/Espruino/xtensa-esp32-elf/bin//xtensa-esp32-elf-gcc
/home/gw/workspace/EspruinoBuildTools/esp32/build
Makefile:18: /home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk: No such file or directory
make: *** No rule to make target '/home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk'. Stop.
Makefile:18: /home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk: No such file or directory
make: *** No rule to make target '/home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk'. Stop.
/home/gw/workspace/EspruinoBuildTools/esp32/build/app
rm: cannot remove 'build/espruino-esp32.elf': No such file or directory
Makefile:18: /home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk: No such file or directory
make: *** No rule to make target '/home/gw/workspace/EspruinoBuildTools/esp32/build/esp-idf/make/project.mk'. Stop.

But it seems like EspruinoBuildTools/esp32/build/esp-idf/make is missing...

Is there some other step that we needed that I'm missing?

Make standalone esp-idf target

@projectgus

platformio/platform-espressif32#19 (comment)

The other thing we've been talking about with other teams in similar situations (Arduino, Micropython) is to add a "make standalone" target, which takes an IDF source tree and a sdkconfig file and spits out a single compiled "lib" directory and a single "include" directory. This greatly simplifies integration into other build systems, although you lose a lot of flexibility.

Would be great to see this - for the esp32 build for espruino we are using a fake app and building tar files for the libs and includes

Can the travis berfore_install be made conditional on board?

@gfwilliams
It seems the way the matrix is applied all of this is brought in for all builds when not necessary:

 - sudo add-apt-repository -y ppa:team-gcc-arm-embedded/ppa
 - sudo apt-get update
 - sudo apt-get install libsdl1.2-dev gcc-arm-embedded
 - curl -Ls http://s3.voneicken.com/xtensa-lx106-elf-20160330.tgx | tar Jxf -
 - curl -Ls http://s3.voneicken.com/esp_iot_sdk_v2.0.0.p1.tgx | tar Jxf -
 - curl -Ls https://github.com/espruino/EspruinoBuildTools/raw/master/esp32/deploy/app.tgz | tar xfz -
 - curl -Ls https://github.com/espruino/EspruinoBuildTools/raw/master/esp32/deploy/esp-idf.tgz | tar xfz -
 - curl -Ls https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-61-gab8375a-5.2.0.tar.gz | tar xfz -

The worst offender is:
https://travis-ci.org/espruino/Espruino/jobs/206521630#L318

sudo apt-get install libsdl1.2-dev gcc-arm-embedded 192 secs

What I'm not sure about is if this before section is saved between each of the build jobs?

https://travis-ci.org/espruino/Espruino/builds/206521620

sdkconfig missing

Installed EspruinoBuildTools following README
It took a very long time to install gcc, about 10 minutes.
Once this was done compiling started and at the end I got this error:
fatal error: sdkconfig.h: No such file or directory
compilation terminated.