From c4bd3dffefc493015752e60bb9d566f989bb8dea Mon Sep 17 00:00:00 2001
From: Rahix <h.w.seiler@gmx.de>
Date: Mon, 10 Apr 2017 18:08:48 +0200
Subject: [PATCH] Add Doc

---
 README.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/README.md b/README.md
index 742b207ed205..c6b98ad129fc 100644
--- a/README.md
+++ b/README.md
@@ -11,3 +11,44 @@ bc = require("bc"):init("<master-address>")
 ```
 where `<master-address>` is the address of you networks master.
 The master is only required to download the base structure file.
+
+The basic idea behind basecontrol is, that network node have a set of **nouns**,
+which represent different values. A computer near a reactor for example could have
+a noun called `power-output`. Network nodes also have **verbs**, actions that other
+nodes can perform. The reactor comuputer could have a `shutdown` verb for example.
+
+The `bc` object has the following methods to interface with verbs and nouns:
+```lua
+-- Retrieve a noun from it's network node
+val = bc:get_noun("<noun>")
+
+-- Set a noun on the local machine
+bc:set_noun("<noun>", value)
+
+-- Call a verb on it's network node
+bc:call_verb("<verb>", param)
+
+-- Register a handler for verbs on the current machine
+bc:on_verb("<verb>", function handler)
+```
+
+Additionally, there is
+```lua
+id = bc:listen_noun("<noun>", event_type, event_arg, function callback)
+```
+
+which is used to register asynchroneous callbacks on noun changes.
+`event_type` is one of
+
+* onchange => whenever the value changes, `event_arg` is ignored
+* onrising => whenever the value gets bigger, `event_arg` is ignored
+* onfalling => whenever the value gets smaller, `event_arg` is ignored
+* onvalue => whenever the value equals `event_arg`
+* onabove => whenever the value is bigger than `event_arg`
+* onbelow => whenever the value smaller than `event_arg`
+
+A listener can be removed using
+
+```lua
+bc:listen_cancel("<noun>", id)
+```