WIP: Batch API and Absolute pen position

API.md

@@ -114,7 +114,7 @@ Content-Type: application/json; charset=UTF-8
 
 ```
 
-#### Request Example (set position)
+#### Request Example (set position via default relative percentage)
 ```javascript
 PUT /v1/pen
 Content-Type: application/json; charset=UTF-8
@@ -126,6 +126,19 @@ Content-Type: application/json; charset=UTF-8
 
 ```
 
+#### Request Example (set position via absolute measurement)
+```javascript
+PUT /v1/pen
+Content-Type: application/json; charset=UTF-8
+
+{
+    "abs": "mm", // Can be 'mm', or 'in'
+    "x": 20.5,
+    "y": 230.25
+}
+
+```
+
 #### Request Example (reset distance counter)
 ```javascript
 PUT /v1/pen
@@ -181,6 +194,11 @@ position. In those cases, the response will return a `202 Accepted` instead of a
 `200 OK`.
  * `lastDuration` in return data can be used in conjunction with ignoreTimeout
 to allow the client to manage timings instead of waiting on the server.
+ * Absolute measurement is only supported by bot configurations that define
+`maxAreaMM` width and height. For non-planar bots like the EggBot, absolute
+measurements of the X axis could never reliably match to real world constants as
+a differing egg size would change this measurement, so sending an `abs` option
+will result in a `406` error.
 
 * * *
 
@@ -624,7 +642,83 @@ Content-Type: application/json; charset=UTF-8
 called. This might have to change though...
 
 
-## 6. Socket.IO & real-time event data streaming
+## 6. Batch
+Overhead on individual ReSTful requests isn't so bad, but add that up over 100k+
+instructions/commands, and that's minutes wasted waiting for all the data just
+to get where it needs to go. If you don't need to know what's happening after
+every request, then _this endpoint is for you!_
+
+This final resource is meant as a catch all, allowing for ordered lists of
+ReSTful endpoint commands to be batch uploaded as either literal JSON data, or
+JSON file & path that the server has access to (either local/or remote HTTP).
+
+### POST /v1/batch
+Post the batch data into the queue. Returns when processing is complete, or
+there's an error.
+
+#### Request: Direct batch data.
+```javascript
+POST /v1/batch
+Content-Type: application/json; charset=UTF-8
+
+[
+  {"DELETE v1/pen": {}},              // Park.
+  {"PUT v1/pen": {"x": 50, "y": 50}}, // Move to 50, 50.
+  {"PUT v1/pen": {"x": 10, "y": 50}}, // Move to 10, 50.
+  {"DELETE v1/pen": {}}               // Park.
+]
+```
+
+#### Request: Batch file (local)
+```javascript
+POST /v1/batch
+Content-Type: application/json; charset=UTF-8
+
+{
+  // JSON file to read from (make sure the server has permission to read the file!)
+  "file": "/tmp/data/cncsererver-batch-example.json"
+}
+```
+
+#### Request: Batch file (remote)
+```javascript
+POST /v1/batch
+Content-Type: application/json; charset=UTF-8
+
+{
+  // Again, make sure the server has HTTP & file access to the file.
+  "file": "http://example.com/batch-data.json"
+}
+```
+
+### Response
+```javascript
+HTTP/1.1 201 OK
+Content-Type: application/json; charset=UTF-8
+
+{
+    // Because some batch processing takes longer than the connection would be
+    // held open for, we simply return a 201 that the command shave been read
+    // and that these will be pushed into the buffer as quickly as possible.
+    "status" : "Parsed 4 commands, queuing"
+}
+```
+
+##### Usage Notes
+ * Command items are parsed and run semi-asynchronously, with each being run as
+ if an individual ReSTful request had been called, without the overhead.
+ * Every command is run with `ignoreTimeout` set, so no need to include it in
+ batch command data. If using the JS wrapper, this is done for you.
+ * Detailed error catching is mostly non-existent, make sure your data is well
+ formed and tested without batching before moving to batch submission.
+ * Return data reporting is exceedingly minimal, so make sure you've
+ decoupled your client from return data (just tie into stream updates).
+ * For batches of > 15k commands, data will stream into the buffer internally
+ for some time, so you have to be careful not to queue any commands in
+ afterwards or commands will be executed in the wrong order.
+
+
+## 7. Socket.IO & real-time event data streaming
 The API has served the project incredibly well, but it was lacking in one
 important aspect: a remote client can receive no updates without asking first,
 no events or data without polling or some other kludge. That is now all