espruino/espruinowebide

The Espruino Web IDE - A Chrome Web App for programming Espruino

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

espruinowebide's Issues

Handle empty port list

Need to show a searching message if no ports available.

Can't see 'Update firmware' by default on Mac

The window is too small, and on Mac the drop-down is huge. Also the 'webcam' button appears when it shouldn't

Icons in splitter hard to press

sorry... after that recent change to make to splitter draggable, you can now drag on the icons in the splitter - and it actually makes them quite hard to press.

I guess there could be some kind of movement of a few pixels before drag starts - or maybe just disable it for anything except the blank areas of the splitter?

Have "code links" upload code to a service and generate an ID instead of sending raw code

I was just thinking, max url length is around 2000 characters so are we going to be limited by how much code can be sent in a URL with the code links we added in #55

Maybe we could use github gists? or do you have any other ideas for sending larger amounts of code?

Show spiny icon when connecting to port

Change usb icon to spinner to show connecting

Quotation marks matter in requires

Originally reported by @voiceofwisdom: espruino/Espruino#223

If you require a module, using double quotes the module loads fine

var nrf = require("NRF24L01P");

However using single quotes produces an error, and does not load the module.

var nrf = require('NRF24L01P');

ERROR: Unable to read file : NOT_READY
WARNING: Module not found

Git based code libraries / snippets

Something I've seen in other software, but I think could be really cool for the Web IDE is to create a git repo of code libraries that can be accessed from the web IDE.

I think in the old UI you had a way to load some code snippets from the web, but I think this was just a repo on your server. If we can use a git repo instead (which all the API's are there, I've done it in a node-webkit project) it'll make it much easier to distribute updates and let other people contribute "Want a code snippet / library in the IDE, just send a pull request".

This could even be what is used when you do require(''), where the name could relate to a branch / folder in the repo.

CTRL+Right Arrow hides the code view

Turns out ctrl+left/right skip to previous/next tokens, but in the Web IDE, ctrl+right arrow also hides the code editor :)

Binary numbers are reported with warnings

I had fixed it so they weren't reported as errors, but it seems that some - esp with leading zeros - cause warnings

Code completion, Syntax check, tool-tip help on right hand side

Resetting the board while terminal connected on windows causes problems

* Terminal Disconnected
* Press Reset
* Release Reset
* Press Disconnect
* **>>> Fine**

* Terminal Connected
* Press Reset
* Release Reset
* **>>> Broken**

* Terminal Connected
* Press Reset
* Press Disconnect
* Release Reset
* **>>> Fine**

Perhaps we can automatically disconnect if we find out that we've lost the connection.

More tutorials

In: https://github.com/espruino/EspruinoWebIDE/tree/gh-pages/data/tutorials

Accessible from (i) -> Tutorials -> Start

NPM support

It'd be nice to have this to stop people moaning, even if it means people will try and load modules that are way too big.

Hopefully if the Web IDE's module loader doesn't find the module on espruino.com, could look for package.json on npm, find the main JS file from it, and load that (potentially minifying it first).

Module loading

Detect 'require('...')' and ensure that the given code is loaded into Espruino (even if there is no SD card)

Add shortcut key support

Allow defining custom key commands along with icons (ie "Cmd + S" for save).

Add throttling when sending data

To fix this kind of thing:

http://forum.espruino.com/conversations/202/#comment1239

Also on non-flow-controlled RS232-based boards.

Step by Step Flasher

The current flasher isn't really that helpful - ideally it'd work as follows:

• user clicks 'Flash Now' button
• Web IDE Automatically disconnects
• prompt the user to reset into bootloader mode (with an ok button)
• Show port selector dialog
• Start flashing process
• Automatically disconnect
• Prompt user to reset board (with an ok button)

Set throttling so it doesn't affect flashing (which is painfully slow otherwise)

Options menu

Font size, colours, etc, etc.

Multiple of the same warning displayed in title bar

I also think it's not obvious enough. I've been using the IDE all day and I only just noticed (and that's because there were 5 warnings!). Ideally it'd write a note in the console too?

Code Style Guidelines

It's a complete mess inside at the moment - a mix of my rough K&R style, and Juergen's style (which is...?).

I'm biased, so I think we should stick with K&R style. Any thoughts? We need something though - I find it extremely hard to understand and the lack of contributions even though this is just a pure JavaScript and HTML project seems to show that something is very wrong.

Serial STM32 programmer required

The Espruino boards can now pretend to be an STM32-style serial bootloader. This means that the software on them can be updated using the Web UI!

All that's needed is a JavaScript implementation of something like this: https://github.com/jsnyder/stm32loader

Change to new Serial API

Docs:

http://developer.chrome.com/apps/serial.html#event-onReceive

Example here:

https://github.com/GoogleChrome/chrome-app-samples/blob/master/serial/ledtoggle/main.js

Minify on the fly

A javascript minifier could be built into the web IDE, so developers can choose to upload a minified version right from their codes.

There are already many minifier built with js itself, I have been using uglifyjs for a long time and it's working great.

What do you guys think?

Terminal code completion

Have the terminal know a list of supported commands, then when typing, if you hit tab, lookup the best match and auto complete for the user.

If multiple items match, auto complete up to the point the matches diverge (ie, if you type d+TAB, and supported commands are digitalWrite, digitalRead, auto complete the word "digital")

Code upload to automatically reset Espruino

Maybe as an option - but by default, every time you upload code it should reset Espruino to the default state.

'Get Link' button?

Now we have: #55

Wouldn't it be cool for users to be able to easily get their code as a URL? I don't want to complicate it, so maybe it could just be something under 'Settings'.

Web IDE occasionally locks up

Usually on other boards where the Serial connection is throttled...

http://forum.espruino.com/conversations/560

Terminal's click+drag to select and copy now broken

Automatic reconnect when connection lost

So it recovers well if there is a hard reset on the board.

Implement UI tour

Tour button exists, but need to implement tour. Use something like tourist.js and use icon buttons as data source.

Give more context when requiring a connection

Hey Gordon,

You mentioned you added the "ensureConnection" method which I think is a cool idea, but I might be tempted to still show a popup message.

For example, if you click on "tutorial" and you aren't connected, it shows the port picker with no explanation as to why, so this could confuse the end user.

It might be worth showing a notification that says "Please connect first" or something.

Also, does the ensureConnection have a callback? such that when you have connected, the thing you tried to access will automatically trigger once you have connected? rather than needing to click the button again.

Matt

File browser for SD card

It'd be pretty cool to build a 'file browser' that let you list and copy files to/from Espruino's SD card. Yes, I know it could be implemented by USB Mass Storage on the device, but this way is a lot more safe as the device doesn't have to somehow split file access between two devices while trying not to corrupt the filesystem.

Option for small title bars

I'm just wondering aloud here, could we cleanly implement a plugin that would switch all the main window icons to small, and would shrink the title bars down?

It doesn't have to look pretty, it'd just be nice to be able to silence anyone that worries about pixels :)

Port selector doesn't scroll

and it probably should... some people have loads of ports

Remove interactive tutorial and link to site instead

Without investing a lot of work to make interactive tutorials more "interactive", I think efforts would be better spent elsewhere so would suggest that the IDE just links to the tutorials section on the site for simplicity.

IDE gets progressively slower

It's because the terminal always re-renders everything. It needs to add only the lines that are new, and ideally it also wants a limit on the amount of lines it remembers... 4000?

Font sizes

It would be nice if there was an option to change the font size as currently it's not good on eyes, especially with this high contrast background on the right pane.

Notifications overlap bottom of terminal window

Yes, I know it's annoying...

But the issue is that if you do anything in the terminal window, chances are you fill it up and the cursor is at the bottom - so next time you connect, you can't do anything until the notification goes.

Not sure quite how we fix this? I guess we could:

• Bump the terminal up when the notification shows
• Have the notification appear only over the code editor, and not the terminal
• Have the notification at the top (might make sense if it was near the connect button?)

Use code editor sidebar as splitter handle

Make sidebar draggable as makes better use of dead space.

Add version number to options dialog

Stop pretending Web IDE isn't just for Espruino

It is, and it's probably just confusing saying it can do other things :)

I've got to go and change the App Store docs, start page, and first step of the tutorial

Differently formatted JavaScript won't work!

If you write:

function foo()
{
}

in the right-hand side, it won't work! We need to fix this with some regex's.

Tooltip-style status updates

It'd be nice if these were bumped up a bit so you could still see the status bar.

At the moment, if you flash a device the 'connected' status update stays showing but it overlaps the progress indicator so it looks like nothing is happening for 5-10 seconds until it fades away.

Minify should report Minification errors

See http://forum.espruino.com/comments/14330/ for details.

Automatic module loader loads requires in strings.

The regex to pull required modules from code tries to load requires that are within a string. Feels like the only way to really fix this is to switch to a lexer instead of regex for pulling out requires.

var test = 'require("test");';

console.log(test);

Wont deploy that chunk of code, due to test failing to load.

Carriage return copy/paste issues on Windows

Also tab...

Graphical code editor to automatically add debounce to setWatch on BTN1

Web App/Espruino seems to just lose data

When just sending data with Chrome's serial API, characters get lost compared to if they were pasted into a terminal app or piped to /dev/ttyXXX.

On MacOS there's a problem with lost characters at a lower level, but this problem is apparent on Windows and Linux.

Re-implement popup close callback

@gordon I notice that we both implemented the constant port checker script and implemented popup closing to kill the interval, but I think your implementation was better (I do a dirty replacement of the close method rather than using an onClose callback).

I think for the sake of some nicer code we should re-implement your method.