Merge pull request #120 from jdoubleu/update-docs

WIP: Update docs

Author: vroland

doc/make.bat

@@ -25,6 +25,8 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
+doxygen.exe
+
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 

doc/requirements.txt

@@ -1,2 +1,3 @@
 breathe>=4
 Sphinx>=3
+sphinx-rtd-theme>=0.5.2

doc/source/getting_started.rst

@@ -93,7 +93,7 @@ The ESP module is now in boot mode.
 Upload the demo program to the board with
 ::
 
-    idf.py build && idf.py flash -b 921600 && idf.py monitor
+    idf.py flash -b 921600 && idf.py monitor
 
 Pressing :code:`RESET` a second time should start the demo program, which will
 output some information on the serial monitor.
@@ -133,6 +133,13 @@ And navigate to :code:`Component config -> E-Paper driver -> Display Type`, sele
 
 to make your code portable.
 
+Enable SPI RAM
+~~~~~~~~~~~~~~~~~~~~~~~~
+The ESP32-WROVER-B comes with an additional 8MB external PSRAM, where the :code:`epd_driver` is going to store ~2MB for its internal frame buffers. 
+Since it is dynamically allocated from the heap, and the built-in SRAM of ~160KB is insufficient, we need to enable external SPI RAM first.
+
+Open the :code:`menuconfig` again (see above) and navigate to :code:`Component config -> ESP32-Specific -> Support for external, SPI-connected RAM` and enable it.
+
 Use with Arduino
 ----------------
 

src/epd_driver/include/epd_driver.h

@@ -252,7 +252,7 @@ void epd_copy_to_framebuffer(EpdRect image_area, const uint8_t *image_data,
  *
  * @param x: Horizontal position in pixels.
  * @param y: Vertical position in pixels.
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_draw_pixel(int x, int y, uint8_t color, uint8_t *framebuffer);
@@ -263,7 +263,7 @@ void epd_draw_pixel(int x, int y, uint8_t color, uint8_t *framebuffer);
  * @param x: Horizontal start position in pixels.
  * @param y: Vertical start position in pixels.
  * @param length: Length of the line in pixels.
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  *  which must be `EPD_WIDTH / 2 * EPD_HEIGHT` bytes large.
  */
@@ -276,7 +276,7 @@ void epd_draw_hline(int x, int y, int length, uint8_t color,
  * @param x: Horizontal start position in pixels.
  * @param y: Vertical start position in pixels.
  * @param length: Length of the line in pixels.
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  *  which must be `EPD_WIDTH / 2 * EPD_HEIGHT` bytes large.
  */
@@ -292,7 +292,7 @@ void epd_fill_circle_helper(int x0, int y0, int r, int corners, int delta,
  * @param x: Center-point x coordinate
  * @param y: Center-point y coordinate
  * @param r: Radius of the circle in pixels
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_draw_circle(int x, int y, int r, uint8_t color, uint8_t *framebuffer);
@@ -303,7 +303,7 @@ void epd_draw_circle(int x, int y, int r, uint8_t color, uint8_t *framebuffer);
  * @param x: Center-point x coordinate
  * @param y: Center-point y coordinate
  * @param r: Radius of the circle in pixels
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_fill_circle(int x, int y, int r, uint8_t color, uint8_t *framebuffer);
@@ -312,7 +312,7 @@ void epd_fill_circle(int x, int y, int r, uint8_t color, uint8_t *framebuffer);
  * Draw a rectanle with no fill color
  *
  * @param rect: The rectangle to draw.
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_draw_rect(EpdRect rect, uint8_t color, uint8_t *framebuffer);
@@ -321,7 +321,7 @@ void epd_draw_rect(EpdRect rect, uint8_t color, uint8_t *framebuffer);
  * Draw a rectanle with fill color
  *
  * @param rect: The rectangle to fill.
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_fill_rect(EpdRect rect, uint8_t color, uint8_t *framebuffer);
@@ -333,7 +333,7 @@ void epd_fill_rect(EpdRect rect, uint8_t color, uint8_t *framebuffer);
  * @param    y0  Start point y coordinate
  * @param    x1  End point x coordinate
  * @param    y1  End point y coordinate
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_draw_line(int x0, int y0, int x1, int y1, uint8_t color,
@@ -348,7 +348,7 @@ void epd_draw_line(int x0, int y0, int x1, int y1, uint8_t color,
  * @param    y1  Vertex #1 y coordinate
  * @param    x2  Vertex #2 x coordinate
  * @param    y2  Vertex #2 y coordinate
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_draw_triangle(int x0, int y0, int x1, int y1, int x2, int y2,
@@ -363,7 +363,7 @@ void epd_draw_triangle(int x0, int y0, int x1, int y1, int x2, int y2,
  * @param    y1  Vertex #1 y coordinate
  * @param    x2  Vertex #2 x coordinate
  * @param    y2  Vertex #2 y coordinate
- * @param color: The gray value of the line (0-255);
+ * @param color: The gray value of the line (see [Colors](#Colors));
  * @param framebuffer: The framebuffer to draw to,
  */
 void epd_fill_triangle(int x0, int y0, int x1, int y1, int x2, int y2,

src/epd_driver/include/epd_highlevel.h

@@ -44,6 +44,17 @@
  * 	That's it! For many application, this will be enough.
  * 	For special applications and requirements, have a
  * 	closer look at the `epd_driver.h` header.
+ *
+ *  Colors
+ *  ======
+ *
+ *  Since most displays only support 16 colors, we're only using the upper 4 bits (nibble) of a byte to detect the color.
+ *
+ * 		char pixel_color = color & 0xF0;
+ *
+ *  So keep in mind, when passing a color to any function, to always set the upper 4 bits, otherwise the color would be black.
+ *
+ *  Possible colors are `0xF0` (white) through `0x80` (median gray) til `0x00` (black).
  */