johnny-five compatible lib for oled devices
npm install oled-js!‘npm version’ !‘downloads over month’
oled js
========================
This repo is a library compatible with Rick Waldron's johnny-five project. It adds support for I2C/SPI compatible monochrome OLED screens. Works with 128 x 32, 128 x 64 and 96 x 16 sized screens, of the SSD1306 OLED/PLED Controller (read the datasheet here).
Got a MicroView from GeekAmmo/SparkFun? That'll work too.
Interested in the nerdy bits going on behind the scenes? Read my blog post about how OLED screens work!
OLED screens are really cool - now you can control them with JavaScript!
If you haven't already, install NodeJS and the Arduino IDE to your computer.
1. npm install oled-js
2. Upload the Standard Firmata sketch (prepackaged with the Arduino IDE) to your Arduino of choice. This can be found under `File > Examples > Firmata > StandardFirmata [[ further help]](http://arduino.cc/en/Guide/HomePage)
+ SDL to pin A4
+ SCL to pin A5
+ RESET to pin 4
Fritzing diagram is here. Look up the correct pins if using a board other than Arduino.
If you'd like to run the demo:
1. git clone this repo (get latest release instead of master branch)npm install
2.
3. Replace width, height, and other values in the options with your own in tests/demoTime.js
4.
`javascript
const five = require('johnny-five');
const Oled = require('oled-js');
const board = new five.Board();
board.on('ready', () => {
console.log('Connected to Arduino, ready.');
const opts = {
width: 128,
height: 64,
address: 0x3D
};
const oled = new Oled(board, five, opts);
// do cool oled things here
});
`
IMPORTANT NOTE: Using SPI will make your screen update and draw VERY slow. Manual hardware SPI over USB is the only way currently to do this within Johnny-Five, which is not optimized for the normal speed you can expect from SPI in general. Sorry about that. Here is a video I took to show this.
Hook up SPI compatible oled to the Arduino. If using an Arduino Uno, pins are as follows:
+ Data/MOSI to pin D9
+ CLK to pin D10
+ D/C to pin D11
+ RST to pin D13
+ CS/SS to pin 12 (you can change this one if you really want to)
Fritzing diagram coming soon.
#### SPI example
`javascript
const five = require('johnny-five');
const Oled = require('oled-js');
const board = new five.Board();
board.on('ready', () => {
console.log('Connected to Arduino, ready.');
const opts = {
width: 128,
height: 64,
secondaryPin: 12
};
const oled = new Oled(board, five, opts);
// do cool oled things here
});
`
MicroView uses SPI, so please see the note about drawing speed in the SPI section above.
This one is pretty simple - use the USB programmer that should have come with your MicroView. Insert the MicroView's header pins into the slots on the USB programmer. Plug it in to your nearest USB port, and you're done! No pin mappings, no sweat.
`javascript
const five = require('johnny-five');
const Oled = require('oled-js');
const board = new five.Board();
board.on('ready', () => {
console.log('Connected to Arduino, ready.');
const opts = {
width: 64,
height: 48,
microview: true
};
const oled = new Oled(board, five, opts);
// do cool oled things here
});
`
Usage:
`javascript`
oled.clearDisplay();
Usage:
`javascript`
oled.dimDisplay(true|false);
Usage:
`javascript`
oled.invertDisplay(true|false);
Usage:
`javascript`
oled.turnOffDisplay();
Usage:
`javascript`
oled.turnOnDisplay();
Each pixel needs an x position, a y position, and a color. Colors can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Usage:
`javascript`
// draws 4 white pixels total
// format: [x, y, color]
oled.drawPixel([
[128, 1, 1],
[128, 32, 1],
[128, 16, 1],
[64, 16, 1]
]);
Arguments:
+ int x0, y0 - start location of line
+ int x1, y1 - end location of line
+ int color - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Usage:
`javascript`
// args: (x0, y0, x1, y1, color)
oled.drawLine(1, 1, 128, 32, 1);
Arguments:
+ int x0, y0 - top left corner of rectangle
+ int width, height - width and height of rectangle in pixels
+ int color - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Usage:
`javascript`
// args: (x0, y0, width, height, color)
oled.fillRect(1, 1, 10, 20, 1);
Arguments:
+ int x0, y0 - top left corner of rectangle
+ int width, height - width and height of rectangle in pixels
+ int color - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Usage:
`javascript`
// args: (x0, y0, width, height, color)
oled.drawRect(1, 1, 10, 20, 1);
Arguments:
+ int x - x of circle's center
+ int y - y of circle's center
+ int r - radius of circle
+ int color - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Usage:
`javascript`
// args: (x, y, r, color)
oled.drawCircle(30, 10, 5, 1);
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Tip: use a NodeJS image parser to get the pixel data, such as pngparse. A demonstration of using this is below.
Example usage:
`
npm install pngparse
`javascript
const pngparse = require('pngparse');
pngparse.parseFile('indexed_file.png', (err, image) => {
oled.drawBitmap(image.data);
});
`
This method is provided as a primitive convenience. A better way to display images is to use NodeJS package png-to-lcd instead. It's just as easy to use as drawBitmap, but is compatible with all image depths (lazy is good!). It will also auto-dither if you choose. You should still resize your image to your screen dimensions. This alternative method is covered below:
`
npm install png-to-lcd
`javascript
const pngtolcd = require('png-to-lcd');
pngtolcd('nyan-cat.png', true, (err, bitmap) => {
oled.buffer = bitmap;
oled.update();
});
`
Usage:
`javascript`
// args: (direction, start, stop)
oled.startScroll('left', 0, 15); // this will scroll an entire 128 x 32 screen
Usage:
`javascript`
oled.stopScroll();
Call setCursor just before writeString().
Usage:
`javascript`
// sets cursor to x = 1, y = 1
oled.setCursor(1, 1);
Arguments:
+ obj font - font object in JSON format (see note below on sourcing a font)
+ int size - font size, as multiplier. Eg. 2 would double size, 3 would triple etc.
+ string text - the actual text you want to show on the display.
+ int color - color of text. Can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.
+ bool wrapping - true applies word wrapping at the screen limit, false for no wrapping. If a long string without spaces is supplied as the text, just letter wrapping will apply instead.
+ int linespacing - amount of spacing between lines of text on the screen. Negative numbers are also ok.
Optional bool as last argument specifies whether screen updates immediately with result. Default is true.
Before all of this text can happen, you need to load a font buffer for use. A good font to start with is NodeJS package oled-font-5x7. Want more options? Try rolling your own font module to require instead, using the oled-js font foundry!
Usage:
`
npm install oled-font-5x7
`javascript
const font = require('oled-font-5x7');
// sets cursor to x = 1, y = 1
oled.setCursor(1, 1);
oled.writeString(font, 1, 'Cats and dogs are really cool animals, you know.', 1, true, 2);
`
Usage:
`javascript``
oled.update();