Merge branch 'feature/rbdr-initial-dev' into develop

[rbdr/sorting-hat] / README.md

diff --git a/README.md b/README.md
index a0aff3ae6f6f0e6f0152b49c508087e314deafd9..75b6b80b0f08521697a544955ddb3c0ff82d5c0d 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,2 +1,64 @@
-# sorting-hat
-A sorting hat, sorts you to a variety of sets of 4
+# Sorting Hat
+
+A sorting hat, sorts you to a variety of sets based on the assignment of
+mind waves.
+
+## Usage
+
+This package can be used as a standalone executable or as a library
+inside other node applications
+
+### As an executable
+
+It can be used as a local or global installation
+
+#### Local Install
+
+```
+$ npm install sorting-hat
+$ npx sorting-hat
+```
+
+#### Global Install
+
+```
+$ npm install -g sorting-hat
+$ sorting-hat
+```
+
+#### Overriding configuration in the binary
+
+The binary uses environment variables to override the defaults
+
+* `SORTING_HAT_DEVICE_LOCATION`: The path from where we'll listen to the
+  mindwave, defaults to `/dev/tty.MindWaveMobile-SerialPo`
+* `SORTING_HAT_MAPPING_STRATEGY`: The strategy used to sort the waves,
+  it defaults to `tmnt`. That is also the only supported value as of
+  right now
+* `SORTING_HAT_PORT`: The port on which we'll start the websocket server
+  to send state updates to the frontends
+
+### As a Library
+
+You can include it in other libraries by requiring the file. For more
+information on the public API and the used data structures, please check
+`doc/README.md`
+
+```
+'use strict';
+
+const sortingHat = new SortingHat({
+  deviceLocation: '/dev/tty.MindWaveMobile-SerialPo',
+  mappingStrategy: 'tmnt',
+  port: 1987
+});
+sortingHat.start();
+```
+
+At the moment it's not built right, so you can't really do much with
+this mode. But you can do it.
+
+## Further Improvements
+
+* Give independent weights to each wave and category so we can balance
+* Allow actual use as a library