{"id":13521390,"url":"https://github.com/noopkat/oled-js","last_synced_at":"2025-04-05T00:07:35.528Z","repository":{"id":20495744,"uuid":"23774074","full_name":"noopkat/oled-js","owner":"noopkat","description":":tv: johnny-five compatible lib for OLED screens","archived":false,"fork":false,"pushed_at":"2023-01-01T18:06:54.000Z","size":619,"stargazers_count":242,"open_issues_count":24,"forks_count":111,"subscribers_count":21,"default_branch":"master","last_synced_at":"2024-10-18T13:56:02.471Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/noopkat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-07T23:47:19.000Z","updated_at":"2024-09-29T02:15:48.000Z","dependencies_parsed_at":"2023-01-13T21:00:15.152Z","dependency_job_id":null,"html_url":"https://github.com/noopkat/oled-js","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noopkat%2Foled-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noopkat%2Foled-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noopkat%2Foled-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/noopkat%2Foled-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/noopkat","download_url":"https://codeload.github.com/noopkat/oled-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247266563,"owners_count":20910836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T06:00:33.759Z","updated_at":"2025-04-05T00:07:35.506Z","avatar_url":"https://github.com/noopkat.png","language":"TypeScript","funding_links":[],"categories":["Libraries and Plugins"],"sub_categories":[],"readme":"![‘npm version’](http://img.shields.io/npm/v/oled-js.svg?style=flat) ![‘downloads over month’](http://img.shields.io/npm/dm/oled-js.svg?style=flat)\n\noled js\n========================\n\n![oled-cat](http://f.cl.ly/items/2G041X2C1o2A1n2D3S18/cat-oled.png)\n\n## What is this?\n\nThis repo is a library compatible with Rick Waldron's [johnny-five](https://github.com/rwaldron/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](http://www.adafruit.com/datasheets/SSD1306.pdf)).\n\nGot a [MicroView](https://www.sparkfun.com/products/12923) from GeekAmmo/SparkFun? That'll work too.\n\nInterested in the nerdy bits going on behind the scenes? [Read my blog post about how OLED screens work](http://meow.noopkat.com/oled-js/)!\n\nOLED screens are really cool - now you can control them with JavaScript!\n\n## Install\n\nIf you haven't already, install [NodeJS](http://nodejs.org/) and the [Arduino IDE](http://arduino.cc/en/Main/Software) to your computer.\n\n1. `npm install oled-js`\n2. Upload the Standard Firmata sketch (prepackaged with the Arduino IDE) to your Arduino of choice. This can be found under ``File \u003e Examples \u003e Firmata \u003e StandardFirmata`` [[ further help]](http://arduino.cc/en/Guide/HomePage)\n\n## I2C screens\nHook up I2C compatible oled to the Arduino. If using an Arduino Uno, pins are as follows:\n\n+ SDL to pin A4\n+ SCL to pin A5\n+ RESET to pin 4\n\n[Fritzing diagram is here](https://raw.githubusercontent.com/noopkat/johnny-five-oled/master/docs/fritzing/i2C_128x32_Uno.png). Look up the correct pins if using a board other than Arduino.\n\nIf you'd like to run the demo:\n\n1. `git clone` this repo (get latest release instead of master branch)\n2. `npm install`\n3. Replace width, height, and other values in the options with your own in tests/demoTime.js\n4. `node tests/demoTime.js`\n\n### I2C example\n\n```javascript\nconst five = require('johnny-five');\nconst Oled = require('oled-js');\n\nconst board = new five.Board();\n\nboard.on('ready', () =\u003e {\n  console.log('Connected to Arduino, ready.');\n\n  const opts = {\n    width: 128,\n    height: 64,\n    address: 0x3D\n  };\n\n  const oled = new Oled(board, five, opts);\n  // do cool oled things here\n});\n\n```\n\n### Wait, how do I find out the I2C address of my OLED screen?\nYeah this sounds like a nightmare, but it's pretty simple! Before uploading standard firmata to your Arduino, upload the [following sketch](http://playground.arduino.cc/Main/I2cScanner) from the Arduino Playground called 'I2C scanner'. Does what it says on the box. Open up your serial monitor, and you'll see your device address pop up there. Make a note of it, then re-upload standard firmata to your Arduino again.\n\n## SPI screens\n\n**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](https://www.youtube.com/watch?v=wHCxlYx2bZY).**\n\nHook up SPI compatible oled to the Arduino. If using an Arduino Uno, pins are as follows:\n\n+ Data/MOSI to pin D9\n+ CLK to pin D10\n+ D/C to pin D11\n+ RST to pin D13\n+ CS/SS to pin 12 (you can change this one if you really want to)\n\nFritzing diagram coming soon.\n\n#### SPI example\n\n```javascript\nconst five = require('johnny-five');\nconst Oled = require('oled-js');\n\nconst board = new five.Board();\n\nboard.on('ready', () =\u003e {\n  console.log('Connected to Arduino, ready.');\n\n  const opts = {\n    width: 128,\n    height: 64,\n    secondaryPin: 12\n  };\n\n  const oled = new Oled(board, five, opts);\n  // do cool oled things here\n});\n\n```\n\n## MicroView\n\n**MicroView uses SPI, so please see the note about drawing speed in the SPI section above.**\n\nThis 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.\n\n### Microview example\n\n```javascript\nconst five = require('johnny-five');\nconst Oled = require('oled-js');\n\nconst board = new five.Board();\n\nboard.on('ready', () =\u003e {\n  console.log('Connected to Arduino, ready.');\n\n  const opts = {\n    width: 64,\n    height: 48,\n    microview: true\n  };\n\n  const oled = new Oled(board, five, opts);\n  // do cool oled things here\n});\n\n```\n\n## Available methods\n\n### clearDisplay\nFills the buffer with 'off' pixels (0x00). Optional bool argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\noled.clearDisplay();\n```\n\n### dimDisplay\nLowers the contrast on the display. This method takes one argument, a boolean. True for dimming, false to restore normal contrast.\n\nUsage:\n```javascript\noled.dimDisplay(true|false);\n```\n\n### invertDisplay\nInverts the pixels on the display. Black becomes white, white becomes black. This method takes one argument, a boolean. True for inverted state, false to restore normal pixel colors.\n\nUsage:\n```javascript\noled.invertDisplay(true|false);\n```\n\n### turnOffDisplay\nTurns the display off.\n\nUsage:\n```javascript\noled.turnOffDisplay();\n```\n\n### turnOnDisplay\nTurns the display on.\n\nUsage:\n```javascript\noled.turnOnDisplay();\n```\n\n\n### drawPixel\nDraws a pixel at a specified position on the display. This method takes one argument: a multi-dimensional array containing either one or more sets of pixels.\n\nEach 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.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\n// draws 4 white pixels total\n// format: [x, y, color]\noled.drawPixel([\n\t[128, 1, 1],\n\t[128, 32, 1],\n\t[128, 16, 1],\n\t[64, 16, 1]\n]);\n```\n\n### drawLine\nDraws a one pixel wide line.\n\nArguments:\n+ int **x0, y0** - start location of line\n+ int **x1, y1** - end location of line\n+ int **color** - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\n// args: (x0, y0, x1, y1, color)\noled.drawLine(1, 1, 128, 32, 1);\n```\n\n### fillRect\nDraws a filled rectangle.\n\nArguments:\n+ int **x0, y0** - top left corner of rectangle\n+ int **width, height** - width and height of rectangle in pixels\n+ int **color** - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\n// args: (x0, y0, width, height, color)\noled.fillRect(1, 1, 10, 20, 1);\n```\n\n### drawRect\nDraws an empty rectangle.\n\nArguments:\n+ int **x0, y0** - top left corner of rectangle\n+ int **width, height** - width and height of rectangle in pixels\n+ int **color** - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\n// args: (x0, y0, width, height, color)\noled.drawRect(1, 1, 10, 20, 1);\n```\n\n### drawCircle\nDraws an empty circle.\n\nArguments:\n+ int **x** - x of circle's center\n+ int **y** - y of circle's center\n+ int **r** - radius of circle\n+ int **color** - can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nUsage:\n```javascript\n// args: (x, y, r, color)\noled.drawCircle(30, 10, 5, 1);\n```\n\n\n### drawBitmap\nDraws a bitmap using raw pixel data returned from an image parser. The image sourced must be monochrome, and indexed to only 2 colors. Resize the bitmap to your screen dimensions first. Using an image editor or ImageMagick might be required.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nTip: use a NodeJS image parser to get the pixel data, such as [pngparse](https://www.npmjs.org/package/pngparse). A demonstration of using this is below.\n\n\nExample usage:\n```\nnpm install pngparse\n```\n\n```javascript\nconst pngparse = require('pngparse');\n\npngparse.parseFile('indexed_file.png', (err, image) =\u003e {\n\toled.drawBitmap(image.data);\n});\n```\n\nThis method is provided as a primitive convenience. A better way to display images is to use NodeJS package [png-to-lcd](https://www.npmjs.org/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:\n\n```\nnpm install png-to-lcd\n```\n\n```javascript\nconst pngtolcd = require('png-to-lcd');\n\npngtolcd('nyan-cat.png', true, (err, bitmap) =\u003e {\n  oled.buffer = bitmap;\n  oled.update();\n});\n```\n\n### startScroll\nScrolls the current display either left or right.\nArguments:\n+ string **direction** - direction of scrolling. 'left' or 'right'\n+ int **start** - starting row of scrolling area\n+ int **stop** - end row of scrolling area\n\nUsage:\n```javascript\n// args: (direction, start, stop)\noled.startScroll('left', 0, 15); // this will scroll an entire 128 x 32 screen\n```\n\n### stopScroll\nStops all current scrolling behaviour.\n\nUsage:\n```javascript\noled.stopScroll();\n```\n\n### setCursor\nSets the x and y position of 'cursor', when about to write text. This effectively helps tell the display where to start typing when writeString() method is called.\n\nCall setCursor just before writeString().\n\nUsage:\n```javascript\n// sets cursor to x = 1, y = 1\noled.setCursor(1, 1);\n```\n\n### writeString\nWrites a string of text to the display.\nCall setCursor() just before, if you need to set starting text position.\n\nArguments:\n+ obj **font** - font object in JSON format (see note below on sourcing a font)\n+ int **size** - font size, as multiplier. Eg. 2 would double size, 3 would triple etc.\n+ string **text** - the actual text you want to show on the display.\n+ int **color** - color of text. Can be specified as either 0 for 'off' or black, and 1 or 255 for 'on' or white.\n+ 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.\n+ int **linespacing** - amount of spacing between lines of text on the screen. Negative numbers are also ok.\n\nOptional bool as last argument specifies whether screen updates immediately with result. Default is true.\n\nBefore 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](https://www.npmjs.org/package/oled-font-5x7). Want more options? Try rolling your own font module to require instead, using the [oled-js font foundry](http://noopkat.github.io/oled-js-font-foundry/)!\n\nUsage:\n```\nnpm install oled-font-5x7\n```\n\n```javascript\nconst font = require('oled-font-5x7');\n\n// sets cursor to x = 1, y = 1\noled.setCursor(1, 1);\noled.writeString(font, 1, 'Cats and dogs are really cool animals, you know.', 1, true, 2);\n```\n\n### update\nSends the entire buffer in its current state to the oled display, effectively syncing the two. This method generally does not need to be called, unless you're messing around with the framebuffer manually before you're ready to sync with the display. It's also needed if you're choosing not to draw on the screen immediately with the built in methods.\n\nUsage:\n```javascript\noled.update();\n```\n\n## Future\n+ better documentation\n+ 16-bit color oled support\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoopkat%2Foled-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnoopkat%2Foled-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnoopkat%2Foled-js/lists"}