Giter VIP home page Giter VIP logo

espruinodocs's Introduction

Espruino Documentation and Code


PLEASE VIEW THIS DOCUMENTATION ON WWW.ESPRUINO.COM - you can even Search. The markdown files in this repository are designed to be parsed by a build script - by viewing them on GitHub you may be missing useful links or information.


This project generates the website and tutorial code for Espruino.com. This also contains the modules that can be required by the Espruino Web IDE. You can contribute to the site and modules in this project.


Documentation files are written GitHub Markdown with additional metadata. Basically, a script that looks for the following (on the start of a line):

* KEYWORDS: Comma,Separated,List ; Defines keywords for this file
* APPEND_KEYWORD: Keyword        ; Append a list of pages that match the keyword
* USES: Comma,Separated,List  ; Defines parts that are used by the given tutorial
* APPEND_USES: part              ; Append a list of pages that have this part in their USES_PARTS list
* APPEND_JSDOC: filename         ; Append JavaScript documentation based on the JS in the given file
* APPEND_PINOUT: boardname       ; Append Pinout for the given board
* BUYFROM: normalprice,bulkprice,link1,link2|optional_name,link3  ; Append a floating 'buy from' window
* APPEND_TOC                     ; Append a table of contents made from H1/H2/H3 (and add them as keywords)
* LIST_LINKS_AS_KEYWORDS         ; Add lists of links `* [...](...)` as keywords

It also looks for a title (second line, after copyright notices) which it uses to create the title of the HTML page (and of links to it).

There are a few extra bits too:

  • [[My Page]] links to a page on the Espruino website
  • [[http://youtu.be/VIDEOID]] puts a video on the page
  • ![Image Title](MyFilename/foo.png) Adds an image. Images should be in a directory named after the filename of the file referencing them (or the same directory as the file referencing them)
  • The first image in the file (or a file named PageName.thumb.jpg/png) is resized and used as the thumbnail. If there's no image on the page at all it's added top-right.

It then converts the Markdown to HTML and shoves it on the Espruino website. Lovely!

JavaScript

Any .js files in examples have a webpage created that uses the comments as markdown, and then adds the code as a code block right at the end.

All other .js files are treated as modules. They are minified using Google's online closure compiler and the SIMPLE_OPTIMISATIONS flag. To get advanced optimisations, you must add the exact text @compilation_level ADVANCED_OPTIMIZATIONS into the comments at the head of the file.

Common keywords

Common keywords for USES/APPEND_USES are:

// Boards
Espruino Board
EspruinoWiFi
Pico
Puck.js
Pixl.js
Bangle.js
Bangle.js2
MDBT42Q
MicroBit
Thingy52

// Other things
Internet       An internet connection
Graphics       Graphics Library
Waveform       Waveform Library
AT             AT Command library
Speaker
PWM
Infrared
ESP8266        ESP8266 attached to an Espruino
BLE            Bluetooth LE (eg via Puck.js) but may need board-specific hardware
Only BLE       Bluetooth LE (eg via Puck.js) but applicable to anything
Web Bluetooth

Common keywords for KEYWORDS/APPEND_KEYWORDS are:

Espruino
Official Board
PCB
Pinout                 Page contains pinout info

Build Requirements

Step 1: Obtain Espruino Source Code & Web Tools

Check out the Espruino and EspruinoWebTools repositories at the same same level as EspruinoDocs folder. Assuming you're in the EspruinoDocs folder...

$ cd ..
$ git clone [email protected]:espruino/Espruino.git`
$ git clone [email protected]:espruino/EspruinoWebTools.git
$ cd EspruinoDocs

Step 2: Install Node.js® and npm

If you have Node.js and npm installed skip this step.

If you haven't got Node.js JavaScript runtime installed or the JavaScript Package managers installed do so via the installation guides below.

On Linux, you may have nodejs and not node in your path. This will lead to issues later on in the build process. This problem is easily solved by running sudo ln -s /usr/bin/nodejs /usr/bin/node which will create a symbolic link, so you can use both node and nodejs at the terminal.

Step 3: Install Required Node Modules

In order to generate the documentation and view it you require several JavaScript packages. To install them issue the following command:

$ npm install

This will install all JavaScript dependencies.

Build Process

Currently they are two build scripts. One bash, one JavaScript.

The bash script does 3 things:

  1. Uses the Espruino source code to generate the pinout diagrams. python is required
  2. Builds the production site at ~/workspace/espruinowebsite
  3. Builds Espruino specific modules and minifies the JavaScript code

The JavaScript build process just builds the documentation in the html folder.

You will have to run build.sh at least once if you want the build.js to work.

To Do a Full Build

Run:

$ ./build.sh

To Build Documentation Only

Note: You've had to have least ran the bash script once for this to build successfully.

Run:

$ npm run build

The output will be placed in the html directory.

View Generated Documentation

You can load a development version of the website locally. It will not look exactly like the production site but you can test your build and links.

$ npm start

Then load up a page in a browser: http://localhost:3040/Original

Troubleshooting

OS X

Set Maximum Open Files

On OSX, most likely the default amount of open files will be set too low. This may cause an error during the build, like: "Error: EMFILE, too many open files 'tasks/File Converter.md'"

Make sure you have at least 1024 for the value of open files.

$ ulimit -n       # see current limit

Increase the limit:

$ ulimit -n 1024  # increase to 1024

Linting

You can lint modules using:

# Install required tools
npm install eslint

# Lint all js files in devices folder
npm run eslintdevices

# Lint all js files in modules folder
npm run eslintmodules

# Lint all js files in boards folder
npm run eslintboards

espruinodocs's People

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

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.

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?

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.

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.

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.

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.

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.

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.

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.

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.

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.

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?

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.

Fake EEPROM module

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

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.

devices/MFRC522.md

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

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())}
                 ^

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

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?

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?

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.

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.