dtex / j5e

Framework for embedded devices using ECMA-419, the ECMAScript® embedded systems API specification, based on Johnny-Five's API

J5e

Control LED's, Servos, Switches, and more with J5e. It runs onboard microcontrollers like the ESP8266 or ESP32. Your code is 100% JavaScript. It does not require node.js, a host server or an SBC to host the app.

J5e is a device framework built upon ECMA-419, the Embedded Systems API Specification for ECMAScript. ECMA-419 provides a standard interface for accessing underlying hardware interfaces (GPIO). J5e's API is based on the Johnny-Five API which has been battle tested over quite some time.

Currently, the only provider that conforms to ECMA-419 is Moddable's IO module for XS which runs on the ESP32 and ESP8266. Hopefully, we will see more soon.

J5e in action

import LED from "j5e/led";

const led = await new LED(14);
led.blink();

New users should check out the Getting Started guide.

Full documentation can be found at www.j5e.dev.

Interested in contributing? Check out CONTRIBUTING.md in this repo.

The documentation repo for J5e can be found on github.

j5e's Issues

coding style question - arguments versus rest parameters

This is a question, not an issue.

These two lines took me a little while to decode:

emit(event) {
  const args = [].slice.call(arguments, 1);

With rest parameters, I think it can be rewritten as:

emit(event, ...args) {

It seems possible that this is an artifact from the Johnny-Five Node implementation. The rest version is almost surely more efficient in XS (and maybe V8 now too?). For j5e, do you intend to keep the original coding style or migrate forward where there are readability and/or runtime benefits? Either seems reasonable: I ask to be able to respect the project's style and goals.

Arrow function causes stack dump

Hi. I'm playing with j5e examples and I've noticed that using arrow function in event listener causes reboot loop and stack dump. Not sure if this should be reported here or in Moddable repo directly.

Code sample:

import Button from 'j5e/button';

const button = await new Button({
  pin: 0,
  mode: 'InputPullUp'
});

button.on('close', () => {
  trace(`CLOSE event, closed: ${button.isClosed}\n`);
});

Console output after uploading:

Exception (28):
epc1=0x40223e35 epc2=0x00000000 epc3=0x00000000 excvaddr=0x00000000 depc=0x00000000
ctx: cont 
sp: 3ffe9940 end: 3ffe9ee0 offset: 01a0
>>>stack>>>
3ffe9ae0:  00000015 3fff868c 3fff0a35 40223935  
3ffe9af0:  3fff5aac 3fff8a04 3fff0a2c 402190bd  
3ffe9b00:  3fff8a04 3fff880c 3fff886c 3fff87dc  
3ffe9b10:  40254d55 0000000a 3fff882c 3fff884c  
3ffe9b20:  00000000 00000000 00000000 000000a1  
3ffe9b30:  00000000 00000000 00000000 000000a1  
3ffe9b40:  00000000 00000000 00000704 3fff874c  
3ffe9b50:  3fff5cd4 3fff5f0c 3fff5bbc 3ffe9ba0  
3ffe9b60:  3fff5b9c 3fff5b7c 3fff602c 3fff8a04  
3ffe9b70:  3fff5bc1 3fff5aac 3fff85fc 4021a2aa  
3ffe9b80:  00000000 00000000 000006a4 3fff5ca0  
3ffe9b90:  3fff5c9c 00000000 00000000 4021acbf  
3ffe9ba0:  4021ac3a 3ffe9ba0 00000000 00000000  
3ffe9bb0:  3fff5c9c 3fff5ca0 3ffe9c20 3fff88bc  
3ffe9bc0:  3fff88cc 3fff88ec 00000000 00000000  
3ffe9bd0:  00000000 4024baea 3ffe9c20 3fff88bc  
3ffe9be0:  3fff8a04 3fff5ccc 3fff5aac 3fff5b7c  
3ffe9bf0:  00000000 3fff5b9c 1e000000 4023809f  
3ffe9c00:  3fff8a04 3fff5aac 3fff88bc 4024baea  
3ffe9c10:  4024b6e8 3fff5e7c 00000000 4021a46c  
3ffe9c20:  4021a445 3ffe9c20 00000000 00000002  
3ffe9c30:  4024b6e8 4024baea 3ffe9c80 3fff88bc  
3ffe9c40:  3fff88cc 3fff88ec 00000008 00000000  
3ffe9c50:  00000000 00000001 3fff0a14 3fff876c  
3ffe9c60:  3fff8a04 3fff88bc 3fff5aac 40262de0  
3ffe9c70:  4024b6e8 00000002 00000000 4021a8ab  
3ffe9c80:  4021a870 3ffe9c80 3fff8a04 00000000  
3ffe9c90:  4024b6e8 4024baea 3ffe9ce0 3fff88bc  
3ffe9ca0:  3fff88cc 3fff88ec 3fff886c 00000000  
3ffe9cb0:  00000000 000000ad 3fff884c 3fff883c  
3ffe9cc0:  3fff8a04 3fff88bc 3fff5aac 00000001  
3ffe9cd0:  3fff8a04 00000000 3fff8a04 402390a2  
3ffe9ce0:  40239072 3ffe9ce0 3fff8a04 4024b6e8  
3ffe9cf0:  00000000 4024baea 00000000 3fff893c  
3ffe9d00:  00000000 00000000 00000000 00000000  
3ffe9d10:  00000000 3fff88ec 3fff5bfc 00000000  
3ffe9d20:  3fff8a04 4024b6e3 00000000 3fff884c  
3ffe9d30:  00000000 4024b6e8 3fff8a04 402391fc  
3ffe9d40:  00000001 4024b6e8 3fff8a04 402399ac  
3ffe9d50:  75746573 656e2f70 726f7774 7378006b  
3ffe9d60:  00000062 00000000 00000000 00000000  
3ffe9d70:  00000000 00000000 00000000 00000000  
3ffe9d80:  00000000 00000000 00000000 00000000  
3ffe9d90:  00000000 00000000 00000000 00000000  
3ffe9da0:  00000000 00000000 00000000 00000000  
3ffe9db0:  00000000 00000000 00000000 00000000  
3ffe9dc0:  00000000 00000000 00000000 00000000  
3ffe9dd0:  00000000 00000000 00000000 00000000  
3ffe9de0:  00000000 00000000 00000000 00000000  
3ffe9df0:  00000000 00000000 00000000 00000000  
3ffe9e00:  00000000 00000000 00000000 00000000  
3ffe9e10:  00000000 00000000 00000000 3ff1fe00  
3ffe9e20:  3ffe9e7c 402836f6 00000000 00000000  
3ffe9e30:  00000000 00000000 00008000 00000000  
3ffe9e40:  00000000 00000000 00008000 40238ff5  
3ffe9e50:  40239790 3ffe9d50 3ffe9f04 00000000  
3ffe9e60:  3fffdad0 3ffe9f0c 00000000 3fff893c  
3ffe9e70:  00000000 00000000 00000000 00000000  
3ffe9e80:  00000000 4024f864 00000000 4020249c  
3ffe9e90:  3fff8a04 4024fd48 00000021 3fff88cc  
3ffe9ea0:  3ffef39c 4027b3b2 3ffe9f04 3ffe9f0c  
3ffe9eb0:  3fffdad0 00000000 3ffe9f04 40246498  
3ffe9ec0:  feefeffe feefeffe feefeffe 40246284  
3ffe9ed0:  feefeffe feefeffe 3ffe8ec0 40100114  
<<<stack<<<

Code works as expected when I change event listener to:

button.on('close', function () {
  trace(`CLOSE event, closed: ${button.isClosed}\n`);
});

fmap function - really Float32?

I bumped into the fmap function when experimenting more with preloading. It generates an exception writing to the Float32Array in f32A:

const f32A = new Float32Array(1);

j5e/lib/fn/index.js

Lines 106 to 109 in 7c393c2

	export function fmap(value, fromLow, fromHigh, toLow, toHigh) {
	f32A[0] = (value - fromLow) * (toHigh - toLow) / (fromHigh - fromLow) + toLow;
	return f32A[0];
	};

To make this work, f32A would need to be allocated at runtime (not during preload). But, it seems to me that fmap really just returns a JavaScript Number, not a Float32 as documented. The Number happens to be truncated so that it can fit into a Float32. The calling code (in my test) is sensor.js > scaled, which should still work with a full resolution float.

Maybe the point of fmap isn't to return a value constrained to a 32-bit float as much as it is to not return an integer (which is what map does)? In that case, it could just be:

 export function fmap(value, fromLow, fromHigh, toLow, toHigh) {
    return (value - fromLow) * (toHigh - toLow) / (fromHigh - fromLow) + toLow;
 };

Fix indentation on code blocks

Again, probably user error

Thermometers should have a Temperature property per ECMA-419

What is Host.io?

Hello. I'm trying to run some examples, but keep getting:

/home/XXX/XXX/XXX/moddable/j5e/lib/fn/index.js (157) # Exception: defaultProvider: get Host: undefined variable!
XS abort: unhandled rejection

I've tried with j5e installed via npm and with repo clone. I'm on latest release of Moddable SDK and I'm using ESP8266 board.
Any ideas, please?

Finish sensor tests

Allow <async> in page title

This one probably is a template issue. Be sure to fix in https://github.com/steveush/foodoc, not here.

Peripherals should have a close method per ECMA 419

Automate docs build with GH actions

Better presentation param object properties

If we could move the properties table to its own row, and span columns 3-5, that might work.

Finish button tests

Use of Object.defineProperties instead of getters?

I'm curious why j5e uses Object.defineProperties to define getters.

Here's a typical example in thee switch class:

j5e/lib/switch/index.js

Lines 57 to 68 in 3390ab3

	Object.defineProperties(this, {
	isClosed: {
	get: () => {
	return Boolean(this.io.read());
	}
	},
	isOpen: {
	get: () => {
	return !Boolean(this.io.read());
	}
	}
	});

This works, but it has both a memory and a time cost. For each instance, two arrow function objects are instantiated and set. In addition, the temporary object passed to Object.defineProperties is created and eventually garbage collected. Using getters directly would seem to provide the same API without incremental memory cost for each instance or added execution time.

  get isClosed() {
    return Boolean(this.io.read()); 
  }
  get isOpen() {
    return !Boolean(this.io.read()); 
  }

Automate npm publishing when a release is tagged

Add "Fork me" link to repo in docs

Animation target is being lost on next()

Links to Tutorials (like Getting Started) do not work in repo readme

They work fine on the docs site. Probably just need to be fully qualified links to the docs site

Add tests for sink drive LEDs

Add readme files to individual classes (for npm)

Website is down

It looks like the website (https://j5e.dev/) is down. I'm very interested in checking this project out for a free JavaScript + hardware workshop that we're giving. The alternative is that we look at DeviceScript, but I like that this project is based on standards, as opposed to DeviceScript.

Needs a linter

Should j5e include an http client/server module(s)?

The IOCP defines TCP Socket classes that can be used for this, and like the other classes, they are low level. When I've built things with J5 that interacted with the world over wifi I always found creating/writing the server to be more of a chore than controlling the hardware itself. Given that, does it make sense to include a barebones HTTP client/server module and possibly a simple router too?

It could be a minimal subset of the node.js HTTP or HTTP2 API.

Not sure this is even doable in a small enough module, but it sure would be nice to make this easier for people.

Fix indentation of required modules

Indentation is additive for some reason. Probably operator error

Port all classes from Johnny-Five

• Accelerometer
• Altimeter
• Animation
• Barometer
• Button
• Compass
• ESC
• Expander
• Fn
• GPS
• Gyro
• Hygrometer
• IMU
• Joystick
• Keypad
• LCD
• Led
• Led.Digits
• Led.Matrix
• Led.RGB
• Light *
• Motion
• Motor
• Multi
• Piezo
• Proximity
• ReflectanceArray
• Relay
• Sensor
• Servo
• ShiftRegister
• System-in-Package
• Stepper
• Switch
• Thermometer

Add comments to Sensor examples in comments

Signature for devices that require more than one IO

Signature for devices that require more than one IO are kind of a mess. Take RGB for example. If you're just passing pin numbers and using the default IO (builtin/pwm) it could be:

const rgb = new RGB([12, 13, 14]);

But if you need usa a specific IO it could be:

const rgb = new RGB({
  pins: [12, 13, 14],
  io: PWM
});

But what if you want to use multiple IO providers? That would have to be:

const rgb = new RGB([
  { pin: 12, io: PWM },
  { pin: 13, io: ExpanderPWM },
  { pin: 14, io: PWM }
]);

or

const rgb = new RGB([
  12,
  { pin: 13, io: ExpanderPWM },
  14
]);

I need to make sure all of these cases are addressed. Any others?

Finish animation tutorial documentation

Namespaced functions aren't showing in documentation

See fn.timer.setInterval

Add debounce option to button

When this lands rwaldron/johnny-five#1690

Sensors should have a sample method per ECMA 419

Servo tests

Add tests for led

fade tests are not well described.

We need tests for pulse.

Github CI tests are freezing.

I suspect Sinon fake timers are the culprit but maybe not.

Test Thermistors with Actual Hardware

The formulas are copied from Johnny-Five, so it should just work but just to be sure these devices need to be tested with actual hardware

• TMP36
• LM35
• LM335
• MF52A103J3470

sensor manifest appears to use within inconsistently

The sensor manifest includes the withinablemodule as j5e/within

j5e/lib/sensor/manifest.json

Line 5 in 3390ab3

"j5e/within": "$(j5e)/lib/withinable/*",

Later it tries to preload the module as j5e/withinable which fails because the module specifier is j5e/within:

j5e/lib/sensor/manifest.json

Lines 9 to 10 in 3390ab3

	"preload": [
	"j5e/withinable",

Should line 5 use j5e/withinable instead?

Not confident that sensor interval is reliable

Tests might prove this, or maybe ADC reads are throttled by Moddable's IO and it won't show up in tests.

Increase font size of sidebar nav

It's too teeny

Should LED default to PWM

Whether an LED can do PWM values depends on the IO it is driving. When a user instantiates an LED without specifying an IO, we assume it will be on builtin/digital. i.e.:

const blinker = await new LED(12); // uses builtin/digital
const pulser = await new LED({ pin: 14, IO: "builtin/pwm" });

Should it be the other way around?

Write switch tests