From a6643a83fbd361f8949e51fd7b3bef5438182b84 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Sergiusz=20=27q3k=27=20Baza=C5=84ski?= <q3k@q3k.org>
Date: Tue, 17 Sep 2013 14:31:04 +0200
Subject: [PATCH] Updated README.

---
 README    | 23 -----------------------
 README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 23 deletions(-)
 delete mode 100644 README
 create mode 100644 README.md

diff --git a/README b/README
deleted file mode 100644
index fffb00d..0000000
--- a/README
+++ /dev/null
@@ -1,23 +0,0 @@
-This is the Hackerspace Warsaw electronic lock mk2 project.
-
-Work in progress! This is a prototype for a TP-Link WR703n based hardware
-solution - with a I2C bus on which there is a MAX7300 IO expander and a PN532
-NFC tag reader. The I2C is software bit-banged by the kernel, drivers for both
-the IO expander and the PN532 are written in Lua.
-
-Files:
-    hslockmk2/                                    - this directory
-             software/
-                      main/                       - code for the central unit of the lock
-                           main.lua               - main Lua script
-                           lua-libs/              - other Lua libraries
-                                   mips-bin/      - C libraries compiled for MIPS/OpenWRT
-                                   luai2c.tar.gz  - C i2c library source
-                                   luasha2.tar.gz - C sha2 library source
-
-                      keypad/                     - AVR code for the keypad               
-             hardware/
-                     keypad/                      - KiCAD files for the keypad PCB
-
-You will additonally need luasec, luaposix and luasocket. But you can easily
-find these in your favourite distribution, or even the OpenWRT source tree.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6452d0a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,46 @@
+### Introduction
+
+This is the Hackerspace Warsaw electronic lock mk2 project.
+
+Work in progress! This is a prototype for a TP-Link WR703n based hardware
+solution - with a I2C bus on which there is a MAX7300 IO expander and a PN532
+NFC tag reader. The I2C is software bit-banged by the kernel, drivers for both
+the IO expander and the PN532 are written in Lua.
+
+### Overview
+
+The hacklock is mae out of two separate pieces of hardware:
+
+* The main lock unit, which runs Linux on a low-power SoC, has one I2C bus
+  to communicate with an NFC reader and some GPIO, and a second I2C bus to 
+  communicate with:
+* The keypad, which is a 10-key (or more) physical keypad attached externally,
+  and is based around and ATMega8 uC (they're cheap!)
+
+### Current hardware status
+
+Right now the project is in a prototype status. The keypad part is nearly
+identical to what will be in production, except that the PCB is home-etched.
+
+The main lock part itself is however based on a TP-Link WR703N router with
+OpenWRT and a software I2C bus. In the future, it will probably be replaced
+woth a custom i.MX233-based 4-layer board.
+
+### Files
+
+* **software/**
+   * **main/**  - code for the central unit of the lock
+      * **main.lua** - main Lua script
+      * lua-libs/ - other Lua libraries
+        * mips-bin/ - C libraries compiled for MIPS/OpenWRT
+        * luai2c.tar.gz**  - C i2c library source
+        * luasha2.tar.gz - C sha2 library source
+   * **keypad/** - AVR code for the keypad               
+      * Makefile - the makefile for the keypad firmware
+* **hardware/**
+   * keypad/ - KiCAD files for the keypad PCB
+
+### Hacking
+
+Feel free to hack around. The whole project, however, is not anywhere near
+release, so things will change around and probably make no sense at the moment.