display_ssd1306.c: note current state and missing pieces.

A few days before being done with this display hardware decided
say good bye. Accordingly I can't continue with writing related
code. Writing down what already works and what's still missing is
probably a good idea, to make sure the next fellow doesn't have
to investigate from scratch.

display_ssd1306.c

@@ -4,6 +4,79 @@
   \brief Code specific to the SSD1306 display.
 */
 
+/**
+  D'oh. Shortly before completing this code, the display hardware died. Shows
+  just black, for whatever reason. Accordingly I can't test new code any longer
+  and writing code without seeing what it does makes no sense.
+
+  What already works:
+
+    - I2C with a queue for small transmissions. Sufficient to queue up sending
+      a rendered character. It's filled by displaybus_write() and drained by
+      the I2C interrupt. Larger transmissions are handled fine, too, but cause
+      wait cycles.
+
+    - 128 byte queue holding characters to send. This queue is filled by
+      display_writechar(). It's drained by display_tick(), which processes,
+      renders and forwards these characters to the I2C queue.
+
+    - Display initialisation.
+
+    - Clearing the display.
+
+    - Writing text with display_writestr_P().
+
+    - Writing formatted text with sendf_P(display_writechar, ...).
+
+    - Current state of code should clear the display at startup, show a
+      greeting message and start displaying current X/Y/Z coordinates, updated
+      once per second. All this not in a particularly pretty fashion, but
+      working.
+
+  TODO list:
+
+    - Procedures like display_clear() and display_set_cursor() should be queued
+      up, too. Just like characters. Fonts start at 0x20, so 0x00..0x1F are
+      available for command sequences. For example, setting the cursor could
+      queue up 0x04 0x01 0x20 (3 bytes) to set the cursor to line 1, column 32.
+      0x04 is the "command", bytes are queued up with display_writechar().
+
+      This is necessary to enforce characters and cursor commands to happen in
+      the right order. Currently, writing a few characters, moving the cursor
+      elsewhere and writing even more characters results in all characters
+      being written to the second position, because characters wait in the
+      queue, while cursor movements are executed immediately.
+
+      Code currently in display_set_cursor() would move to display_tick(), then.
+
+    - Lot's of prettification. Like a nice background picture with the Teacup
+      logo, like "Welcome to Teacup" as a greeting screen, like writing numbers
+      to readable places and so on.
+
+    - Get rid of i2c_test.c.
+
+    - Allow different fonts. Already paraphrased in font.h and font.c. Needs
+      a selection menu in Configtool, of course, the same way one can select
+      display types.
+
+    - It's a bit unclear wether this 'last_byte' flag to displaybus_write() is
+      really ideal. Fact is, I2C transmissions need a start and an explicite
+      ending. Also thinkable would be a displaybus_finalise() function
+      which puts the marker in place. Saves a lot of shuffling parameters
+      around.
+
+      Yet another option would be to make sure the I2C send buffer is drained
+      befpre sending the next transmission. I2C code already finalises a
+      transmission on buffer drain, so only _reliable_ waiting needs an
+      implementation.
+
+      Each variant needs testing, which one gets away with the smallest code.
+      Smallest code is likely the fastest code as well.
+
+    - Here's an assistant to convert pictures/bitmaps into C code readable by
+      the compiler: http://en.radzio.dxp.pl/bitmap_converter/
+*/
+
 #include "display.h"
 
 #if defined TEACUP_C_INCLUDE && defined DISPLAY_TYPE_SSD1306