Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@gfwilliams
gfwilliams committed Mar 8, 2017
1 parent b565bb4 commit 3282387
Show file tree
Hide file tree
Showing 4 changed files with 52 additions and 33 deletions.
10 changes: 6 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,6 @@ If you are a board manufacturer interested in getting your board officially supp
* ST NUCLEO-F411RE - WORKING
* ESP8266 - WORKING - Reasonably stable, but expect to find issues
* Arduino (AVR) - NOT POSSIBLE due to the Hardward architecture of AVRs, even though it would fit into an ATMEGA2560. If `avr-gcc` ever gains an easy way to emulate Von Neumann architecture then it might be portable, but for now it isn't.
* Arduino (ARM) - very doable, but no work has been done on this.


Modification
Expand All @@ -127,12 +126,15 @@ Any more questions? [ask on the forum.](http://www.espruino.com/Forum)

### Porting to new 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.
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.

* 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 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`
Expand Down
28 changes: 16 additions & 12 deletions README_BuildProcess.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ Directories and Files
* `doxygen/`: Directory for auto-generated code documentation - see [doxygen/README.md](doxygen/README.md) for more info
* `gen/`: Auto-Generated Source Files
* `libs/`: Optional libraries to include in Espruino (Math, Filesystem, Graphics, etc)
* `make/`: Makefile fragments for each architecture
* `misc/`: Other useful things
* `scripts/`: Scripts for generating files in gen, and for analysing code/compilation/etc
* `src/`: Main source code
Expand All @@ -25,18 +26,18 @@ Build Commands
Building for an Espruino board is generally done by typing:

```
BOARDNAME=1 make
BOARD=BOARDNAME make
```

And for release, by typing:

```
RELEASE=1 BOARDNAME=1 make
RELEASE=1 BOARD=BOARDNAME make
```

Valid board names are in comments at the head of the [`Makefile`](https://github.com/espruino/Espruino/blob/master/Makefile)..

Release builds have all the assertions removed, saving space. Normal builds still have the assertions, and debug builds (with `DEBUG=1` have more debug info in the assertions, as well as the debug info needed for proper GDB debugging).
Release builds have all the assertions removed, reducing flash usage. Normal builds still have the assertions, and debug builds (with `DEBUG=1` have more debug info in the assertions, as well as the debug info needed for proper GDB debugging).

The Make system has the following targets:

Expand All @@ -48,9 +49,9 @@ The Make system has the following targets:
Build Process
-------------

* Most build logic is in the [`Makefile`](https://github.com/espruino/Espruino/blob/master/Makefile).
* An `ifdef BOARDNAME` in the Makefile sets up some specific build options, as well as what gets included (eg. `USE_NET=1`). The `BOARD` variable references a [Board Definition File](#boarddefinition) in `boards/`.
* `boards/$BOARD.py` is read, and various information (chip family, part number, binary name, whether it has a bootloader) is read out into variables in the Makefile. **Note:** in the future more of the build options should be inferred from the `BOARD.py` file,
* Overall build logic is in the [`Makefile`](https://github.com/espruino/Espruino/blob/master/Makefile).
* The [Board Definition File](#boarddefinition) in `boards/$BOARD.py` is parsed by [`scripts/get_makefile_decls.py`](scripts/get_makefile_decls.py) to work out extra definitions for the Makefile (chip family, part number, binary name, whether it has a bootloader), which control the build.
* Architecture-specic build logic is in the [`make`](https://github.com/espruino/Espruino/tree/master/make) directory - this is called based off `family` in the [Board Definition File](#boarddefinition) in `boards/`.
* The `Makefile` adds source files to `$SOURCES`, and 'wrapper' source files to `$WRAPPERSOURCES`. [Wrapper files](#wrapperfiles) are files that contain functions that are exposed to JS.
* The script [`scripts/build_platform_config.py`](scripts/build_platform_config.py) is run which generates `gen/platform_config.h` from `boards/$BOARD.py` - this contains information like the amount of RAM, as well as buffer sizes and the amount of variables that will be stored.
* The script [`scripts/build_pininfo.py`](scripts/build_pininfo.py) creates [the pin definitions](#pindefinitions) and puts them in `gen/jspininfo.c`
Expand Down Expand Up @@ -78,7 +79,8 @@ Board Definition File <a name="boarddefinition">
The board definition files are `.py` files that reside in the [`boards`](boards) folder (for example [the Pico one](boards/PICO_R1_3.py)). They're used all over the place:

* To work out the binary's name
* To help choose what gets built in the Makefile
* To choose which libraries get built in via the Makefile
* To specify the architecture-specific Makefile fragments are used
* To create `gen/platform_config.h` via [`scripts/build_playform_config.py`](scripts/build_playform_config.py)
* To generate the linker file `gen/linker.ld` using [`scripts/build_linker.py`](scripts/build_linker.py). Mainly STM32-based targets only.
* To create [the pin definitions](#pindefinitions)
Expand All @@ -95,6 +97,10 @@ These contain:
* `bootloader` - whether the binary image needs compiling with a special USB-VCP bootloader (Espruino boards only)
* `binary_name` - the name of the binary that'll be produced
* `binaries` - available binaries - this is used by the Web IDE to allow the user to choose which binary to upload
* `build` - controls what gets build via the Makefile:
* `optimizeflags` - flags like `-O3` to give to the compiler
* `libraries` - list of libraries to include
* `makefile` - list of commands/definitions to execute in the Makefile

### chip

Expand All @@ -110,13 +116,13 @@ These contain:
* Number of `adc`s
* Number of `dac`s
* `saved_code` - how and where to save JS code in the chip's flash memory
* The `address` of the start of the code in flash memory. Note that on STM32 chips this
* The `address` of the start of the code in flash memory. Note that on STM32 chips this
is at 0x08000000 even though code executes from 0x00000000 (the two areas are mirrored but
0x00000000 is faster to execute from while 0x08000000 is what's needed for writing to flash)
* The `page_size` in bytes of the first flash page containing code (not used now?)
* The number of flash `pages` we're using for code (not used now?)
* `flash_available` in KB, used as a sanity check by [`scripts/check_size.sh`](scripts/check_size.sh) after the build completes
* `place_text_section` what address to start the program code at - This is `0` if not specified,
* `place_text_section` what address to start the program code at - This is `0` if not specified,
but is useful in devices like the Pico where varying page sizes mean that the program code may
be located after the saved program code (and/or bootloader)

Expand All @@ -139,7 +145,7 @@ Stuff you can use is `LED1`-`LED8`, `BTN1`-`BTN4`, `USB`, `LCD` (for boards with
Pin Definitions <a name="pindefinitions">
---------------

The pin definitions are created by [`scripts/build_pininfo.py`](`scripts/build_pininfo.py`) and are stored in `gen/jspininfo.c`. The script calls
The pin definitions are created by [`scripts/build_pininfo.py`](`scripts/build_pininfo.py`) and are stored in `gen/jspininfo.c`. The script calls
`get_pins` in `boards/$BOARD.py` and a structure of the following form is returned:

```
Expand Down Expand Up @@ -209,5 +215,3 @@ The wrapper files are also parsed by:

* [`scripts/build_docs.py`](scripts/build_docs.py), which builds the HTML file used for the Espruino [Reference](http://www.espruino.com/Reference).
* [`scripts/build_tern_json.js`](scripts/build_tern_json.js), which generates a JSON description of all functions (along with their documentation) which is used for code completion in the Web IDE *and to parse all code examples in order to produce the 'Examples' links in the [Reference](http://www.espruino.com/Reference)*.


45 changes: 29 additions & 16 deletions README_Building.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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:
To build and run Espruino on the OS that one is using is as simple as the following, if prerequisits are met:

```bash
make clean && make
Expand All @@ -22,6 +22,19 @@ Espruino is easy to build under Linux, for either for Espruino running on Linux

The current reference OS for building is Ubuntu 16.04.1 LTS, and the following can ensure problem free development:

### Easy Method : provision-framework.sh

Simply run the following with the name of your board to set
your computer up ready for a build:

```bash
source scripts/provision-framework.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.

### for Espruino

```bash
Expand All @@ -38,7 +51,7 @@ make clean && make
chmod +x espruino && sudo cp espruino /usr/local/bin
```

### for an example of cross compilation for the puck.js
### for an example of cross compilation for Puck.js

Having successfully created an native OS Espruino, try a cross compilation.

Expand All @@ -52,7 +65,7 @@ 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 PUCKJS=1 RELEASE=1 make
make clean && DFU_UPDATE_BUILD=1 BOARD=PUCKJS RELEASE=1 make
ls -l *puckjs*
```

Expand Down Expand Up @@ -102,20 +115,20 @@ After a successful OpenWRT build, [OpenWRT Espruino packages](https://github.com
### for STM32 Boards (incl. [Espruino Board](http://www.espruino.com/EspruinoBoard)

```bash
make clean && YOUR_BOARD_NAME=1 RELEASE=1 make
make clean && BOARD=YOUR_BOARD_NAME RELEASE=1 make
```

* See the top of Makefile for board names
* `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.
* `BOARD=BOARDNAME RELEASE=1 make serialflash` will flash to /dev/ttyUSB0 using the STM32 serial bootloader (what's needed for the Espruino and HY boards)
* `BOARD=BOARDNAME 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 the `Makefile`
* Knock out some functionality (like `USE_GRAPHICS=1`) that you don't need in the `Makefile`

**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.
**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.

### for [Nordic Semiconductor's nRF51/nRF52 series devices](https://www.nordicsemi.com/eng/Products/Bluetooth-low-energy)

Expand All @@ -131,7 +144,7 @@ Dependant on the board, either usb or bluetooth can be used to program the board
The puck.js is based on the nRF52

```bash
make clean && DFU_UPDATE_BUILD=1 PUCKJS=1 RELEASE=1 make
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.
Expand All @@ -142,14 +155,14 @@ See <https://www.espruino.com/Puck.js+Quick+Start> for information concerning tr
All boards based on the nRF52 have RAM and Flash to support Espruino without feature disablement.

```bash
make clean && NRF52832DK=1 RELEASE=1 make
make clean && BOARD=NRF52832DK RELEASE=1 make
```

#### for [micro:bit](http://microbit.org/)

The micro:bit is based on the nRF51.

* ```make clean && MICROBIT=1 RELEASE=1 make```
* ```make clean && BOARD=MICROBIT RELEASE=1 make```
* Drop the hex generated on the micro:bit drive and it is then an Espruino.

Note:
Expand All @@ -163,7 +176,7 @@ Note:
All boards based on the nRF51 are limited in RAM and Flash so many features are disabled.

```bash
make clean && NRF51822DK=1 RELEASE=1 make
make clean && BOARD=NRF51822DK RELEASE=1 make
```

### for esp8266
Expand All @@ -175,7 +188,7 @@ In order to compile for the esp8266 on Linux several pre-requisites have to be i

To run make you need to pass a couple of environment variables to `make`. These include:

* `ESP8266_BOARD=1`
* `BOARD=ESP8266_BOARD`
* `FLASH_4MB=1` if you have an esp-12
* `ESP8266_SDK_ROOT=<Path to the 1.4 SDK>`
* `PATH=<Path to esp-open-sdk/xtensa-lx106-elf/bin/>`
Expand All @@ -186,7 +199,7 @@ The easiest is to place the following lines into a script, adapt it to your need
```bash

#! /bin/bash
export ESP8266_BOARD=1
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/
Expand Down Expand Up @@ -289,7 +302,7 @@ Note:
* `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
*`exit`.
* `exit`.
* On the host OS, the following are useful vagrant commands
* `vagrant suspend`
* will pause the VM
Expand All @@ -314,7 +327,7 @@ Note: VirtualBox Guest Additions from VirtualBox are required.
* 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 ESPRUINO_1V3=1 RELEASE=1 make serialflash`
* 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.
**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.
2 changes: 1 addition & 1 deletion boards/PUCKJS.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
'default_console_rx' : "D29",
'default_console_baudrate' : "9600",
# Number of variables can be WAY higher on this board
'variables' : 2000, # How many variables are allocated for Espruino to use. RAM will be overflowed if this number is too high and code won't compile.
'variables' : 1800, # How many variables are allocated for Espruino to use. RAM will be overflowed if this number is too high and code won't compile.
'bootloader' : 1,
'binary_name' : 'espruino_%v_puckjs.hex',
'build' : {
Expand Down

0 comments on commit 3282387

Please sign in to comment.