Adds readme and an example

Also renames oink to @bsdavidson/oink to avoid an npm conflict.

KT-15 #done
KT-21 #done

.gitignore

@@ -1,6 +1,7 @@
+/.vscode
+/.nyc_output
+/coverage
 /lib
-/node_modules
-.vscode
+node_modules
 yarn-error.log
-/coverage
-/.nyc_output
+yarn.lock

LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Brian Davidson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -0,0 +1,82 @@
+# Oink
+
+[![Build Status](https://travis-ci.org/bsdavidson/oink.svg?branch=master)](https://travis-ci.org/bsdavidson/oink) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/bsdavidson/oink/blob/master/LICENSE)
+
+Oink is a Node library for controlling Onkyo receivers. This was inspired by the
+Python [onkyo-eiscp] library. Oink also makes use of a customized version of
+onkyo-eiscp's YAML file for code generation.
+
+Oink provides:
+
+- A device class to communicate with receivers, and the ability to automatically
+  discover receivers on a local network.
+- An HTTP handler to provide a REST API to communicate with a device.
+- A generated module of [helper functions] to make it easier
+  to send commands to a device.
+
+[onkyo-eiscp]: https://github.com/miracle2k/onkyo-eiscp
+[helper functions]: https://github.com/bsdavidson/oink/tree/master/src/commands
+
+## Installation
+
+```bash
+yarn add @bsdavidson/oink
+```
+
+## Example
+
+```javascript
+const http = require("http");
+const {createDeviceHandler, discover} = require("oink");
+
+async function main() {
+  // Oink's discover method will search for devices on the network and return
+  // an array of DiscoveredDevice objects.
+  let discovered;
+  do {
+    discovered = await discover({deviceLimit: 1});
+  } while (!discovered.length);
+
+  // If you already know the host and port of your reciever,
+  // you can call new Device() to create a Device instance
+  // manually, rather than use discovery. For example:
+  //
+  //     const device = new Device("10.0.0.120", 60128, "1");
+  //
+  // But in this case, since we used discovery, you can call toDevice() on a
+  // DiscoveredDevice instance to create a Device instance that can be used to
+  // communicate with the receiver.
+  const device = discovered[0].toDevice();
+
+  // Device instances emit a data event for packets from the receiver.
+  // Each incoming packet is a Packet instance containing the
+  // command (e.g. PWR, MVL, ...), a parameter (e.g. "01", "somestring", ...),
+  // and the device type (typically "1")
+  device.on("data", packet => {
+    console.log(packet);
+  });
+
+  // Call connect on a device to establish a persistant connection.
+  await device.connect();
+
+  // Send a command to a device by creating a command packet and passing it to
+  // the send() method.
+  //
+  // Send an UP command to the Main Volume Level (MVL)
+  const response = await device.sendCommand("MVL", "UP");
+  console.log(response); // Packet { command: 'MVL', parameter: '1F', deviceType: '1' }
+
+  // Oink also provides a way to create a standard HTTP handler which provides a
+  // simple REST API to send and recieve commands to a device. For example,
+  // to query the current master volume level (MVL), make a GET request like the
+  // following:
+  //
+  //    $ curl http://127.0.0.1:3000/MVL
+  //    {"command":"MVL","parameter":"1F","deviceType":"1"}
+  http.createServer(createDeviceHandler(device)).listen(3000);
+}
+
+main();
+```
+
+[Oink.](http://gph.is/1OoF29s)

__tests__/integration.ts

@@ -114,8 +114,8 @@ describe("createDeviceHandler", () => {
     test("should allow you to query a command", async () => {
       const response = await harness.request("GET", "/MVL?timeout=100");
       expect(response).toEqual({
-        statusCode: 200,
-        body: {parameter: "01"}
+        body: {command: "MVL", deviceType: "1", parameter: "01"},
+        statusCode: 200
       });
     });
 
@@ -136,8 +136,8 @@ describe("createDeviceHandler", () => {
         JSON.stringify({parameter: "DOWN"})
       );
       expect(response).toEqual({
-        statusCode: 200,
-        body: {parameter: "01"}
+        body: {command: "MVL", deviceType: "1", parameter: "01"},
+        statusCode: 200
       });
     });
 

build/eiscp-commands.yaml

@@ -1,4 +1,4 @@
-# Last generated
+# Originally generated
 #   by import_protocol_doc.py
 #   from ISCP_AVR_134.xlsx
 #   at 2017-01-27 20:35:03.115748
@@ -7,6 +7,9 @@
 # automatic import didn't and often can't do right. These changes
 # should be tracked in source control, so they can be merged with
 # new generated versions of the file.
+#
+# This file has been customized for Oink to provide non-conflicting names
+# for easier code generation.
 
 main:
   PWR:

build/generate-commands.ts

@@ -200,6 +200,12 @@ function renderZone(name: string, commands: OnkyoDataCommandMap): string {
 
   return prettier.format(
     `
+ /**
+ * Last generated by generate-commands.ts
+ * at ${new Date().toISOString()} from
+ * eiscp-commands.yaml
+ **/
+
       import {Packet} from "../protocol";
       ${lines.join("\n")}
     `,

example/main.js

@@ -0,0 +1,51 @@
+const http = require("http");
+const {createDeviceHandler, discover} = require("@bsdavidson/oink");
+
+async function main() {
+  // Oink's discover method will search for devices on the network and return
+  // an array of DiscoveredDevice objects.
+  let discovered;
+  do {
+    discovered = await discover({deviceLimit: 1});
+  } while (!discovered.length);
+
+  // If you already know the host and port of your reciever,
+  // you can call new Device() to create a Device instance
+  // manually, rather than use discovery. For example:
+  //
+  //     const device = new Device("10.0.0.120", 60128, "1");
+  //
+  // But in this case, since we used discovery, you can call toDevice() on a
+  // DiscoveredDevice instance to create a Device instance that can be used to
+  // communicate with the receiver.
+  const device = discovered[0].toDevice();
+
+  // Device instances emit a data event for packets from the receiver.
+  // Each incoming packet is a Packet instance containing the
+  // command (e.g. PWR, MVL, ...), a parameter (e.g. "01", "somestring", ...),
+  // and the device type (typically "1")
+  device.on("data", packet => {
+    console.log(packet);
+  });
+
+  // Call connect on a device to establish a persistant connection.
+  await device.connect();
+
+  // Send a command to a device by creating a command packet and passing it to
+  // the send() method.
+  //
+  // Send an UP command to the Main Volume Level (MVL)
+  const response = await device.sendCommand("MVL", "UP");
+  console.log(response); // Packet { command: 'MVL', parameter: '1F', deviceType: '1' }
+
+  // Oink also provides a way to create a standard HTTP handler which provides a
+  // simple REST API to send and recieve commands to a device. For example,
+  // to query the current master volume level (MVL), make a GET request like the
+  // following:
+  //
+  //    $ curl http://127.0.0.1:3000/MVL
+  //    {"command":"MVL","parameter":"1F","deviceType":"1"}
+  http.createServer(createDeviceHandler(device)).listen(3000);
+}
+
+main();

example/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "oink-example",
+  "version": "1.0.0",
+  "description": "An example app using Oink",
+  "main": "main.js",
+  "license": "MIT",
+  "dependencies": {
+    "@bsdavidson/oink": "^0.0.0"
+  }
+}

package.json

@@ -1,10 +1,11 @@
 {
-  "name": "oink",
-  "version": "0.0.1",
+  "name": "@bsdavidson/oink",
+  "version": "0.1.1",
   "description": "A module for interacting with Onkyo recievers",
   "main": "lib/index.js",
   "author": "Brian Davidson",
   "license": "MIT",
+  "homepage": "https://github.com/bsdavidson/oink",
   "devDependencies": {
     "@types/jest": "^23.3.0",
     "@types/js-yaml": "^3.11.2",
@@ -16,6 +17,7 @@
     "rimraf": "^2.6.2",
     "ts-jest": "^23.0.1",
     "ts-node": "^7.0.0",
+    "ts-node-dev": "^1.0.0-pre.26",
     "typescript": "^2.9.2"
   },
   "scripts": {

src/api.ts

@@ -120,17 +120,10 @@ export async function handleCommand(
   switch (ctx.req.method) {
     case "GET":
       // GET requests are only for queries.
-      return {parameter: await sendQuery(device, command, timeout)};
+      return await sendQuery(device, command, timeout);
 
     case "POST":
-      return {
-        parameter: await sendCommand(
-          device,
-          command,
-          ctx.body.parameter,
-          timeout
-        )
-      };
+      return await sendCommand(device, command, ctx.body.parameter, timeout);
 
     default:
       throw new ContextError("Invalid request method", 405);

src/commands/dock.ts

@@ -1,3 +1,9 @@
+/**
+ * Last generated by generate-commands.ts
+ * at 2018-07-24T20:18:21.400Z from
+ * eiscp-commands.yaml
+ **/
+
 import { Packet } from "../protocol";
 
 /**

src/commands/main.ts

@@ -1,3 +1,9 @@
+/**
+ * Last generated by generate-commands.ts
+ * at 2018-07-24T20:18:21.689Z from
+ * eiscp-commands.yaml
+ **/
+
 import { Packet } from "../protocol";
 
 /**

src/commands/zone2.ts

@@ -1,3 +1,9 @@
+/**
+ * Last generated by generate-commands.ts
+ * at 2018-07-24T20:18:22.043Z from
+ * eiscp-commands.yaml
+ **/
+
 import { Packet } from "../protocol";
 
 /**

src/commands/zone3.ts

@@ -1,3 +1,9 @@
+/**
+ * Last generated by generate-commands.ts
+ * at 2018-07-24T20:18:22.100Z from
+ * eiscp-commands.yaml
+ **/
+
 import { Packet } from "../protocol";
 
 /**

src/commands/zone4.ts

@@ -1,3 +1,9 @@
+/**
+ * Last generated by generate-commands.ts
+ * at 2018-07-24T20:18:22.146Z from
+ * eiscp-commands.yaml
+ **/
+
 import { Packet } from "../protocol";
 
 /**

src/device.ts

@@ -107,7 +107,7 @@ export class Device extends EventEmitter {
         if (data.command === packet.command) {
           clearTimeout(timeout);
           this.off("data", handleData);
-          resolve(data.parameter);
+          resolve(data);
         }
       };
 

src/index.ts

@@ -1,2 +1,6 @@
-export {Packet} from "./protocol";
+export {createDeviceHandler} from "./api";
 export {Device, discover, DiscoveredDevice} from "./device";
+export {Packet} from "./protocol";
+
+import * as commands from "./commands";
+export {commands};