From bbfe51499f7364a25322a24b6418f2187962e5f9 Mon Sep 17 00:00:00 2001
From: Conor Patrick <conorpp94@gmail.com>
Date: Wed, 20 Nov 2019 11:31:52 -0500
Subject: [PATCH] document

---
 docs/solo/porting.md | 48 ++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml           |  1 +
 2 files changed, 49 insertions(+)
 create mode 100644 docs/solo/porting.md

diff --git a/docs/solo/porting.md b/docs/solo/porting.md
new file mode 100644
index 0000000..a8121d8
--- /dev/null
+++ b/docs/solo/porting.md
@@ -0,0 +1,48 @@
+# Usage and Porting
+
+Solo is designed to be used as a library or ported to other platforms easily.  Here is an example
+`main()` function.
+
+```c
+int main()
+{
+    uint8_t hidmsg[64];
+    uint32_t t1 = 0;
+
+    device_init();
+    memset(hidmsg,0,sizeof(hidmsg));
+
+    while(1)
+    {
+
+        if (usbhid_recv(hidmsg) > 0)
+        {
+            ctaphid_handle_packet(hidmsg);      // pass into libsolo!
+            memset(hidmsg, 0, sizeof(hidmsg));
+        }
+
+
+        ctaphid_check_timeouts();
+    }
+
+}
+
+```
+
+`ctaphid_handle_packet(hidmsg);` is the entrance into the HID layer of libsolo, and will buffer packets and pass them
+into FIDO2 or U2F layers.
+
+Everything in the library is cross-platform, and it makes calls to functions defined
+in `fido2/device.h` to do possibly platform specific things.  To get the library to compile
+and run, you only need to implement one of these functions: `usbhid_send(uint8_t * send)`, which
+is called by the library to send a 64 byte packet over a USB HID endpoint.
+
+The rest of the definitions in `fido2/device.h` are not required to compile and run so you can
+immediately hit the ground running and iterative add what else you need.  You'll definitely want
+to continue implementing other functions in `fido2/device.h`.  For example, no data will be stored
+persistently until you define how it can be done!
+
+For examples, check out the build for STM32L4 and PC.
+
+If there's something that doesn't work for you -- send a pull request!  It's better if we can
+work together off of the same repo and not fork.
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index b52f005..9baf801 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -18,6 +18,7 @@ nav:
     - Application Ideas: solo/application-ideas.md
     - Running on Nucleo32 board: solo/nucleo32-board.md
     - Signed update process: solo/signed-updates.md
+    - Usage and Porting guide: solo/porting.md
     - Code documentation: solo/code-overview.md
     - Contributing Code: solo/contributing.md
     - Contributing Docs: solo/documenting.md