search

smaffer / espvgax

ESP8266 VGA Library for Arduino
159 stars 25 forks source link

readme

ESPVGAX Library for ESP8266

COPYRIGHT (C) 2018 Sandro Maffiodo
smaffer@gmail.com
http://www.sandromaffiodo.com

splash

YouTube videos:

Some photos:

What is ESPVGAX?

This is a VGA library for ESP8266.
To use this library you need only 1 resistor and one DSUB15 connector.
This library require an ESP8266 with all GPIO exposed, like ESP-12E, NodeMCU-12E board or any board that expose GPIO5 (D1), GPIO4 (D2) and GPIO13 (D7)

Credits

VGA signal generation based on https://github.com/hchunhui/esp-vga (thanks for your awesome works).

Video

The library implement a 512x480px framebuffer with 1bpp, where each pixel is stored as a single bit. The framebuffer is stored inside RAM and require 30720 bytes. The VGA signal generation is stable only if you do not use any other hardware feature of the MCU (like Wifi or Serial). If you want, in theory, you can use another board to drive the one that use ESPVGAX library, by writing a comunication layer based on SoftwareSerial or I2C.

The library support an extendend coloring system that allow you to enable two additionals colors for each line of pixels. For example you can wire the primary color to GREEN (framebuffer 1bit color will be green or black) and enable RED and BLUE dynamically, for each line of pixels. This mode is called "line coloring"

In addition, you can change the background color from BLACK to another color by wiring the D5 PIN. This mode is called "background coloring".

Wiring

For the basic usage you need:

Then connect them like the following schema.

wire.png

NOTE: The DSUB15 connector is shown from rear view

Colors combination and Additional colors

The 2 colors generated from ESPVGAX library are not predefined. You can connect the D7 PIN with one of the VGA DSUB15 RGB PINS, selecting the color combination that you prefer.

These are all of the possible combinations, done without additional components:

color0.png

color1.png

If you want to use the "background coloring" mode, you can wire the D5 PIN to one of the others VGA DSUB15 RGB PINS, for example, if you wire the D5 PIN to the VGA BLUE PIN, you can obtain these colors combinations:

color2.png

The same things can be done by wiring D5 PIN to GREEN or RED, and wiring the remaining VGA PINS in some other combinations.

If you want you can use the "line coloring" mode, by enabling the ESPVGAX_EXTRA_COLORS constant (inside ESPVGAX.h) and wiring the VGA RGB PINS in some combinations. For example, if you wire the primary color (D7 PIN) to RED and wire GREEN and BLUE to the additional line colors PINS (D0 and D4) you can obtain these colors, selected line by line (setLineProp method):

color3.png

Keep in mind that the line colors cannot be changed inside a single line. These additional color PINS will be enabled or disabled before generating the signal of a single line of pixels.

WARNING if you enable ESPVGAX_EXTRA_COLORS and wire D0 and D4 PINS you cannot flash the MCU firmware. D4 PIN need to be detached before flashing the MCU firmware or the flashing process will not work.

32bit and 8bit Framebuffer

The internal 512x480px framebuffer is implemented as a 32bit framebuffer, with 16 32bit words for each line of pixels. You can write to the framebuffer 32 pixels at a time (putpixel32 method), in this case the write operation will be faster than writing single pixels. The same framebuffer can be written 8 pixels at a time, by using a different memory pointer and a dedicated set of methods (putpixel8, xorpixel8, etc ..).

Interrupt and Timers

ESPVGAX library will use only one timer: TIMER0 or TIMER1. You can choose one of these timers by changing the ESPVGAX_TIMER constant inside ESPVGAX.h header. From my tests the TIMER1 seem to be more stable.

80Mhz or 160Mhz

This library support both 80Mhz and 160Mhz MCU running speed. Keep in mind that the 160Mhz version will not work with the hardware TIMER0.

Limitations

When this library is running (begin/end methods) some Arduino functions cannot be used. For example, if you return from the loop function, Arduino firmware will call yield function. This function can generate some noises to the VGA signal. This event also happen if you call the Arduino delay function. More noises will be generated if you try to use Wifi and ESPVGAX both at the same time... To prevent noises you need to temporarely turn off ESPVGAX and restart that after Wifi comunications (see /examples/Wifi for example). Instead of using these Arduino functions you can use the ESPVGAX versions: delay(), rand(), srand().

Library usage

To use the ESPVGAX library you need to include its header

#include <ESPVGAX.h>

ESPVGAX class is static, so you can use the class without create an instance of it:

void setup() {
  ESPVGAX::begin();
}”

Or, if you prefer, you can create your instance, but keep in mind that cannot be more than one ESPVGAX instance at a time:

ESPVGAX vga;

void setup() {
  vga.begin();
}

Examples

This is a simple example of putpixel8 function. The putpixel8 function put 8 pixels at a time. The following code create a pattern of colors in the setup function:

  #include <ESPVGAX.h>

ESPVGAX vga;

void setup() {
  vga.begin();
  vga.clear(0xAA);
  for (int y=0; y!=ESPVGAX_HEIGHT; y++) {
    for (int x=0; x!=ESPVGAX_BWIDTH; x++) {
      vga.putpixel8(x, y, vga.rand()%2);
    }
  }
}
void loop() {
  while (1) {
    //never return from loop(). never call delay() or yield() functions
  }
}

For the others examples, you can load and build one of the examples released with ESPVGAX:

Fonts

These fonts are released with ESPVGAX, inside the /fonts/ folder:

Tools

1bitimage

To convert an image to the ESPVGAX format (1bit per pixel) i wrote a simple webapp that reads an image and create a C/C++ source file to be used with ESPVGAX.

The image that you can use as a source must use only two colors, black and white images will work fine.

The source file of the webapp is inside the tools directory. You can open 1bitimage.html with your webbrowser and run it locally. I use Google Chrome, dunno if works with other webbrowsers.

1bitfont

With 1bitfont you can create your fonts from a single image and convert them to be used with ESPVGAX library. The tool reads an image that contains all font's glyphs are separated from one or more vertical blank lines. All glyphs are extracted and converted to a C/C++ source file.

1bitfont is a webapp, like 1bitimage, that can run locally on your webbrowser.

FAQ

Happy hacking

If you find a way to optimize the speed of the library, or find a way to remove screen flickering let me know!

Happy hacking!