diff --git a/README.md b/README.md
index bb750e7..d49b11e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,24 @@
-firmware template for ST STM8S micro-controller.
-includes register definitions using macros and structures.
+STM8S003 firmware for the [I²C to HD44780 adapter](https://git.cuvoodoo.info/kingkevin/board/src/branch/i2c_hd44780).
+
+I²C commands (first byte).
+
+simplified commands:
+
+- 0x0 INIT: initialize LCD, as 2-line, 5x8 dots, no blinking or cursor
+- 0x1 LINE1: write to line 1, followed by ASCII text
+- 0x2 LINE2: write to line 2, followed by ASCII text
+- 0x3 DISPLAY_ON: turn display on
+- 0x4 DISPLAY_OFF: turn display off
+- 0x5 BRIGHTNESS: set backlight brightness, followed by 0-255 value
+
+raw instructions, directly mapping to HD44780, followed by instruction byte or data bytes if applicable:
+
+- 0x6 CLEAR_DISPLAY
+- 0x7 RETURN_HOME
+- 0x8 ENTRY_MODE_SET
+- 0x9 DISPLAY
+- 0xa CURSOR_DISPLAY_SHIFT
+- 0xb FUNCTION_SET
+- 0xc CGRAM_ADDR
+- 0xd DDRAM_ADDR
+- 0xe DATA