Git Product home page Git Product logo

espruinodocs's Introduction

Espruino JavaScript for Microcontrollers

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

https://www.espruino.com           Join the chat at https://gitter.im/espruino/Espruino

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:

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

espruinodocs's People

Contributors

akoslukacs avatar baljo avatar bartmichu avatar beaufortfrancois avatar canyoncasa avatar chalkers avatar cwbudde avatar edwinm avatar gfwilliams avatar jbaumbach avatar jhrichards avatar jokl70 avatar loop23 avatar mabecker avatar mgg1010 avatar mvaldesdeleon avatar nkolban avatar opichals avatar programmicha avatar rmcubed avatar samehhady avatar spencekonde avatar the-alchemist avatar thyttan avatar tomgidden avatar tve avatar urish avatar wilberforce avatar yerpj avatar zigrin avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

espruinodocs's Issues

Issue with MFRC552 Module

When uploading the code to the Espruino i receive the error

Uncaught Error: Field or method does not already exist, and can't create it on undefined
 at line 1 col 190
...("MRFC522 Request Error "+a);a=this.r(20);return this.ra(18,...
                               ^
in function "req" called from line 1 col 35
{this.w(26,7);return 0<this.req(38).length}
                                   ^
 at line 1 col 36
{this.w(26,7);return 0<this.req(38).length}
                                    ^
in function "isNewCard" called from line 1 col 17
{this.isNewCard()&&a(this.getCardSerial())}
                 ^

Coding style guideline for modules

The way JS code is written/formatted can have some surprising effects on memory usage and performance, so I think it would make sense if you add some general rules in the "Writing Modules" section.

ESP8266 getIP() returns incorrect result

I'm getting 192.168.4.1 as the IP when I do wifi.getIP().

The IP address that the ESP8266 actually gets is 192.168.2.102 (in my case). It seems that it's getting the IP that it would use when acting as an access point, rather than the IP it has as a client. If possible, the ESP8266WiFi module should return the appropriate IP address for the mode the ESP8266 is currently operating in.

make it possible to send multiple pixels at once with graphics

A lot of the functions with IO allow to send a lot of data at once since, as the performance page indicates, there is a noticeable overhead with executing code. Make it possible to send an array of pixel coordinates or even an array filled with the desired colours at each row,col position to make addressing the display more efficient.

Speed up DS18B20

The writeSpad function uses 'arguments', which is quite slow as every mention of it causes the array to be recreated. It'd be better explicitly labelling each write.

devices/MFRC522.md

The page says this is an I2C connection, but it documents an SPI connection instead

I2C.setup() and SPI.setup() documentation in espruino.com/Reference don't list default baud/bitrate

Sure, I could ask, and I remember Gordon saying the default for I2C was 50khz (50000), but AFAIK, nobody's ever asked this about SPI, so god only knows what the default speed for that is.

This is the kind of information that should be listed in the reference, along with the minimum and maximum possible. It's not clear to me how these reference pages are generated, and whether I should be reporting this issue here, or in the main espruino repo.

ESP8266 needs error handling.

Sometimes, the ESP8266 will refuse to respond to AT+RST, particularly immediately after power-on.

In this case, we should wait a short time, and try again.

Additionally, after a failure like what I was experiencing on the forums, it might make sense for the Espruino to wait a second, then do AT+RST, and then fire a callback to that gets the ESP8266 back into it's old state (maybe just the initial setup callback? ) to try to get it working again.

hmac.js hexdigest bug

@ganehag I just had this e-mail:

I have found a bug, the hexdigest() function called to produce a string from a precomputed hmac sometimes wrong

for example

hmac.create("passwordditest", "ETH01", hashlib.sha256).hexdigest();
produces a string of 61 byte length:

4ae1de552d368dd65e45eca75bcfd91c94511e07d4039d441eb222820fc33

but the real output must be

4a0e1de552d368dd65e45eca750bcf0d91c94511e07d4039d441eb222820fc33 

Any ideas?

device modules space indentation

Hello Gordon,
It's not a big issue at all but I've noticed some style inconsistencies in the device modules i.e. usually it is two spaces for indents, but sometimes it's only one space, and then sometimes it's a mix of them in the same file.
Do you mind if I go through these files and fix it so that it's always two spaces? (in accordance to Espruino/CONTRIBUTING)

Use JSDOC documentation for modules

Since updating build.js, we can now do:

Reference
--------------

* APPEND_JSDOC: modulename.js

and can then add simple documentation to each module in the form of:

/** My description
 second line if we want it */
FooBar.prototype.hello = function() {
}

/** Another */
exports.woot = function() {
}

See devices/NRF24L01P.js as an example. We now just need to bash through all the modules and do this.

Note that it doesn't cope with defining functions inside an export.connect function. Ideas for how to sort that appreciated - but for now it can just be documented in a comment above.

http doc incorrectly states that it is only available on Raspberry Pi

The documentation for the http currently reads:

This library allows you to create http servers and make http requests
NOTE: This is currently only available in the Raspberry Pi version
This is a cut-down version of node.js's library

Please see http://nodemanual.org/latest/nodejs_ref_guide/http.html

To use this, you must type var http = require('http') to get access to the library

NOTE: The HTTP client + server send in ~8 byte chunks. This is normally fine but big servers - eg. Google will reject requests made like this (DDoS protection?)

  1. http library is available on Espruino Board
  2. You don't have to do var http = require('http') - you can just do require('http').whatever() when using it.
  3. Is it still true about 8 byte chunks?

peripherals/Waveform.md

The "samples" argument to Waveform looks weird in many of these examples:

var w = new Waveform(256);
for (var i=0;i<1024;i++) w.buffer[i] = 128+Math.sin(i_Math.PI/128)_127;

Why does the loop go to 1024 when there are only 256 samples in the Waveform?

no docs for fs.open()

Per docs:

This is the stream related file IO library.
To use this, you must type var fd = require('fs').open('filepath','flags','mode') to open a file stream.

However, fs.open is not documented, and there's no description of the "flags" argument.

./peripherals/Waveform.md

In the "CREATING AUDIO FILES FOR ESPRUINO" section it instructs to save at 4000Hz, but in the double buffer example the sound is played at 11025Hz.

Fake EEPROM module

That uses STM32F1Flash/etc to fake an EEPROM using free on-board flash memory

tasks/File Converter.md allows files to be larger then 20KiB

Today I wanted to convert a large file, but of course that didn't work because it was simply to large.
The console had thrown me a Uncaught RangeError: Maximum call stack size exceeded. The file was larger then 20KiB and it didn't leave the "File too long - must be less than 20kB".
That's because it still executes var b64Str = 'atob("'+btoa(String.fromCharCode.apply(null, bytes))+'")';, when this is too large js will just crash.
I'll make a pull request that fixes this.

Thermistor module expects 10k pullup

It seems to me at least - and this should be different depending on the thermistor. Maybe an option is needed.

Also 'Thermistors' should probably reference it better, and circuit diagram ought to really show current limiting resistor as optional.

provide option for setInterval to execute immediately

The current behaviour for setInterval is to wait the defined time and then execute the function, until the interval is cleared. Since setInterval is the primary function for periodic events, it might be a good idea to add an option to execute the function immediately instead of first waiting for the defined timeout.

For example, a LED could be set to blink using setInterval, where the option would determine if you want the LED to blink immediately or only after the first timeout occurred.

tutorials/Pico CPU Monitor.md

Hey there,
just checked the nice gadget on Mac OSX 10.9

The command "paste" failed as it was in need of the filename. If you give "-" as filename it will read the piped data.

As i'm german it was difficult to find another problem, because the decimal point in germany is "," not "." and bc was not able to calculate … maybe a little hint to mention for non experts.

There was a little typo, because the device was missing a "b" in "cu.usmodem"

The complete command that worked for me, besides setting my locale to english, was:
echo -e "draw(ps -A -o pcpu | tail -n+2 | paste -sd+ - | bc)\n" > /dev/cu.usbmodem*;

Thanks again and awesome work!

Ability to create module reference from JSDOC

Probably just add it to build.js. Detect:

* APPEND_JSDOC: file.js

And then shove in JSDoc code created by reading that file. This would really improve documentation - especially as modules get more complex.

Console CLI

I have created a console interface, node library, and grunt task to make interacting with the espruino from a normal file system very easy. Would you have any issue with me adding them to the docs?

CLI and Node.js library
Grunt task.

Individual addressable lights that came with the kickstarter package works on 6400000

I tried the lights with the demo code from the documentation, but couldn't get them to work. At first, all I was able to accomplish was getting one light turned on in white instead of red as I wanted to.

After some trial and error I got them working with 6400000 baud instead of 3200000.

I connected the lights to A7 and now this, and other code works:

SPI1.setup({baud:6400000, mosi:A7});
SPI1.send4bit([200,0,20], 0b0001, 0b0011); // pink

Maybe it is a good idea to edit the docs and suggest using 6400000 when 3200000 doesn't work?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.