Add tutorial and "danger: experimental" banner to README.

README.md

@@ -1,5 +1,4 @@
-![Project Tox](https://raw.github.com/TokTok/toxcore/master/other/tox.png "Project Tox")
-***
+# ![Project Tox](https://raw.github.com/TokTok/toxcore/master/other/tox.png "Project Tox")
 
 **Current build status:** [![Build Status](https://travis-ci.org/TokTok/c-toxcore.svg?branch=master)](https://travis-ci.org/TokTok/c-toxcore)
 **Current Coverage:** [![Coverage Status](https://coveralls.io/repos/github/TokTok/toxcore/badge.svg?branch=master)](https://coveralls.io/github/TokTok/toxcore?branch=master)
@@ -8,56 +7,168 @@
 
 **IRC Channels:** Users: [#tox@freenode](https://webchat.freenode.net/?channels=tox), Developers: [#toktok@freenode](https://webchat.freenode.net/?channels=toktok)
 
+## What is Tox
+
+Tox is a peer to peer (serverless) instant messenger aimed at making security
+and privacy easy to obtain for regular users. It uses
+[NaCl](https://nacl.cr.yp.to/) for its encryption and authentication.
+
+## IMPORTANT!
+
+### ![Danger: Experimental](other/tox-warning.png)
+
+This is an **experimental** cryptographic network library. It has not been
+formally audited by an independent third party that specializes in
+cryptography or cryptanalysis. **Use this library at your own risk.**
+
+The underlying crypto library [NaCl](https://nacl.cr.yp.to/install.html)
+provides reliable encryption, but the security model has not yet been fully
+specified. See [issue 210](https://github.com/TokTok/c-toxcore/issues/210) for
+a discussion on developing a threat model. See other issues for known
+weaknesses (e.g. [issue 426](https://github.com/TokTok/c-toxcore/issues/426)
+describes what can happen if your secret key is stolen).
+
 ## Toxcore Development Roadmap
-This Roadmap is somewhat tentative, but should give you a good idea of where
-we're going, and where we've been.
 
-Currently unsorted, the following is intended to function as a discussion guide
-to developers/contributors.
+The roadmap and changelog are generated from GitHub issues. You may view them
+on the website, where they are updated at least once every 24 hours:
 
-### In Progress
-- [ ] Toxcore
-    - [ ] 100% unit testing
-    - [ ] Make ToxAV stateless
-    - [ ] Allow a single toxcore instance to handle multiple keypairs (or 'clients')
-    - [ ] Consistent naming scheme throughout toxcore
-    - [X] Make toxcore stateless
-- [ ] Messenger
-    - [ ] Improve group chat implementation
-    - [ ] Improve A/V implementation
-    - [ ] Multiple device support
+-   Changelog: https://toktok.ltd/changelog/c-toxcore
+-   Roadmap: https://toktok.ltd/roadmap/c-toxcore
 
-### Done
-- [X] Create Toxcore
-- [X] Create DHT
-- [X] Create Onion
-- [X] Implement Crypto
-- [X] Create Messenger
+## Installing toxcore
 
-## Q&A:
+Detailed installation instructions can be found in [INSTALL.md](INSTALL.md).
 
-### What is Tox?
+In a nutshell, if you have [libsodium](https://github.com/jedisct1/libsodium)
+or [nacl](https://nacl.cr.yp.to/install.html) installed, run:
 
-Tox is a fully encrypted, censor resistant, private, distributed network library with a focus on personal communications.
+```sh
+autoreconf -fi
+mkdir _build && cd _build
+../configure
+make
+sudo make install
+```
 
-### No, really, what's Tox?
+If you have [libvpx](https://github.com/webmproject/libvpx) and
+[opus](https://github.com/xiph/opus) installed, the above will also build the
+A/V library for multimedia chats.
 
-It's a VERY secure Instant Messenger that supports Text, Audio/Video calls, group chats, audio group chats, and file transfers. There's dozens, but our advantage is we put security first, from day 1. We didn't decide to add it in after.
+## Using toxcore
 
-### What are your goals with Tox?
+The simplest "hello world" example could be an echo bot. Here we will walk
+through the implementation of a simple bot.
 
-We want Tox to be as simple as possible while remaining as secure as possible.
+### Creating the tox instance
 
-## Documentation:
-- [Compiling](/INSTALL.md)
-- [DHT Protocol](/docs/updates/DHT.md)<br />
-- [Crypto](/docs/updates/Crypto.md)<br />
+All toxcore API functions work with error parameters. They are enums with one
+`OK` value and several error codes that describe the different situations in
+which the function might fail.
 
-## The Complex Stuff:
-### UDP vs. TCP
-Tox must use UDP simply because [hole punching](https://en.wikipedia.org/wiki/UDP_hole_punching) with TCP is not as reliable.
-However, Tox does use [TCP relays](/docs/TCP_Network.txt) as a fallback if it encounters a firewall that prevents UDP hole punching.
+```c
+TOX_ERR_NEW err_new;
+Tox *tox = tox_new(NULL, &err_new);
+if (err_new != TOX_ERR_NEW_OK) {
+  fprintf(stderr, "tox_new failed with error code %d\n", err_new);
+  exit(1);
+}
+```
 
-### Connecting & Communicating
-Every peer is represented as a [byte string](https://en.wikipedia.org/wiki/String_(computer_science)) (the public key [Tox ID] of the peer). By using torrent-style DHT, peers can find the IP of other peers by using their Tox ID. Once the IP is obtained, peers can initiate a [secure](/docs/updates/Crypto.md) connection with each other. Once the connection is made, peers can exchange messages, send files, start video chats, etc. using encrypted communications.
+Here, we simply exit the program, but in a real client you will probably want
+to do some error handling and proper error reporting to the user. The `NULL`
+argument given to the first parameter of `tox_new` is the `Tox_Options`. It
+contains various write-once network settings and allows you to load a
+previously serialised instance. See [toxcore/tox.h](tox.h) for details.
 
+### Setting up callbacks
+
+Toxcore works with callbacks that you can register to listen for certain
+events. Examples of such events are "friend request received" or "friend sent
+a message". Search the API for `tox_callback_*` to find all of them.
+
+Here, we will set up callbacks for receiving friend requests and receiving
+messages. We will always accept any friend request (because we're a bot), and
+when we receive a message, we send it back to the sender.
+
+```c
+tox_callback_friend_request(tox, handle_friend_request);
+tox_callback_friend_message(tox, handle_friend_message);
+```
+
+These two function calls set up the callbacks. Now we also need to implement
+these "handle" functions.
+
+### Handle friend requests
+
+```c
+static void handle_friend_request(
+  Tox *tox, const uint8_t *public_key, const uint8_t *message, size_t length,
+  void *user_data) {
+  // Accept the friend request:
+  TOX_ERR_FRIEND_ADD err_friend_add;
+  tox_friend_add_norequest(tox, public_key, &err_friend_add);
+  if (err_friend_add != TOX_ERR_FRIEND_ADD_OK) {
+    fprintf(stderr, "unable to add friend: %d\n", err_friend_add);
+  }
+}
+```
+
+The `tox_friend_add_norequest` function adds the friend without sending them a
+friend request. Since we already got a friend request, this is the right thing
+to do. If you wanted to send a friend request yourself, you would use
+`tox_friend_add`, which has an extra parameter for the message.
+
+### Handle messages
+
+Now, when the friend sends us a message, we want to respond to them by sending
+them the same message back. This will be our "echo".
+
+```c
+static void handle_friend_message(
+  Tox *tox, uint32_t friend_number, TOX_MESSAGE_TYPE type,
+  const uint8_t *message, size_t length,
+  void *user_data) {
+  TOX_ERR_FRIEND_SEND_MESSAGE err_send;
+  tox_friend_send_message(tox, friend_number, type, message, length,
+    &err_send);
+  if (err_send != TOX_ERR_FRIEND_SEND_MESSAGE_OK) {
+    fprintf(stderr, "unable to send message back to friend %d: %d\n",
+      friend_number, err_send);
+  }
+}
+```
+
+That's it for the setup. Now we want to actually run the bot.
+
+### Main event loop
+
+Toxcore works with a main event loop function `tox_iterate` that you need to
+call at a certain frequency dictated by `tox_iteration_interval`. This is a
+polling function that receives new network messages and processes them.
+
+```c
+while (true) {
+  usleep(1000 * tox_iteration_interval(tox));
+  tox_iterate(tox, NULL);
+}
+```
+
+That's it! Now you have a working echo bot. The only problem is that since Tox
+works with public keys, and you can't really guess your bot's public key, you
+can't add it as a friend in your client. For this, we need to call another API
+function: `tox_self_get_address(tox, address)`. This will fill the 38 byte
+friend address into the `address` buffer. You can then display that binary
+string as hex and input it into your client. Writing a `bin2hex` function is
+left as exercise for the reader.
+
+We glossed over a lot of details, such as the user data which we passed to
+`tox_iterate` (passing `NULL`), bootstrapping into an actual network (this bot
+will work in the LAN, but not on an internet server) and the fact that we now
+have no clean way of stopping the bot (`while (true)`). If you want to write a
+real bot, you will probably want to read up on all the API functions. Consult
+the API documentation in [toxcore/tox.h](tox.h) for more information.
+
+### Other resources
+
+- [Another echo bot](https://wiki.tox.chat/developers/client_examples/echo_bot)