VirtualRC: initial docs

local.yaml

@@ -36,6 +36,9 @@ x-tagGroups:
     tags:
       - Device Schedules
       - Group Schedules
+  - name: Virtual Remote Control
+    tags:
+      - Virtual Remote Control
   - name: Sidekick
     tags:
       - Sidekick

local/paths.yaml

@@ -41,6 +41,10 @@
     $ref: ../skeds/paths.yaml#/SkedsPath
 /v2/devices/{device_id}/skeds/{sked_id}:
     $ref: ../skeds/paths.yaml#/SkedPath
+/v2/devices/{device_id}/vrc:
+    $ref: ../vrc/paths.yaml#/VrcPath
+/v2/devices/{device_id}/vrc/keystream:
+    $ref: ../vrc/paths.yaml#/VrcKeystreamPath
 /v2/groups:
     $ref: ../groups/paths.yaml#/GroupsPath
 /v2/groups/{group_id}:

vrc/paths.yaml

@@ -0,0 +1,129 @@
+VrcPath:
+  get:
+    $ref: ../vrc/paths.yaml#/Get
+  patch:
+    $ref: ../vrc/paths.yaml#/Patch
+  parameters:
+    - in: path
+      name: device_id
+      required: true
+      schema:
+        type: number
+  description: testing 123
+  tags:
+  - Virtual Remote Control
+
+VrcKeystreamPath:
+  put:
+    $ref: ../vrc/paths.yaml#/PutKey
+  parameters:
+  - in: path
+    name: device_id
+    required: true
+    schema:
+      type: number
+  description: testing 123
+  tags:
+  - Virtual Remote Control
+
+Get:
+  description: |
+    Check enabled status of virtual remote for specified device.
+  responses:
+    '200':
+      content:
+        application/json:
+          schema:
+            required: true
+            $ref: schemas.yaml#/Vrc
+      description: Get Vrc info
+    '401':
+      $ref: ../common/responses.yaml#/Unauthorized
+    '404':
+      $ref: ../common/responses.yaml#/NotFound
+    '500':
+      $ref: ../common/responses.yaml#/InternalServerError
+  security:
+    - OAuth: ["oauth2"]
+  summary: Get Vrc info
+  tags:
+  - Virtual Remote Control
+
+Patch:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required: true
+          $ref: schemas.yaml#/Vrc
+  responses:
+    '200':
+      content:
+        application/json:
+          schema:
+            $ref: schemas.yaml#/Vrc
+      description: Enable or disable Vrc
+    '401':
+      $ref: ../common/responses.yaml#/Unauthorized
+    '404':
+      $ref: ../common/responses.yaml#/NotFound
+    '500':
+      $ref: ../common/responses.yaml#/InternalServerError
+  security:
+  - BasicAuth: []
+  summary: Enable or disable Vrc
+  tags:
+  - Virtual Remote Control
+
+PutKey:
+  requestBody:
+    content:
+      application/json:
+        schema:
+          required: true
+          $ref: schemas.yaml#/VrcKeystream
+  responses:
+    '200':
+      content:
+        application/json:
+          schema:
+            $ref: schemas.yaml#/VrcKeystream
+      description: Send a virtual key event
+    '401':
+      $ref: ../common/responses.yaml#/Unauthorized
+    '404':
+      $ref: ../common/responses.yaml#/NotFound
+    '500':
+      $ref: ../common/responses.yaml#/InternalServerError
+  security:
+  - BasicAuth: []
+  summary: Send a virtual key event
+  description: |
+    Example:
+
+    User Behavior:
+      - user taps 1
+      - then holds 1
+      - adds 2
+      - taps 3
+      - adds 3
+      - then releases 1 and 2 at same time
+      - then releases 3
+
+    Events sent:
+
+        {event: TAP, key: 1}
+        {event: HOLD_START, key: 1}
+        {event: HOLD, key: 1, hold_ms:301}
+        {event: HOLD, key: 1, hold_ms:604}
+        {event: HOLD_START, key: 2}
+        {event: HOLD, key: [1, 2], hold_ms:302}
+        {event: TAP, key: 3}
+        {event: HOLD, key: [1, 2], hold_ms:602}
+        {event: HOLD_START, key: 3}
+        {event: HOLD_END key: [1, 2], hold_ms: 20}
+        {event: HOLD, key: 3, hold_ms:320}
+        {event: HOLD_END key: 3, hold_ms: 400}
+
+  tags:
+  - Virtual Remote Control

vrc/schemas.yaml

@@ -0,0 +1,55 @@
+Vrc:
+  properties:
+    enabled:
+      example: true
+      type: boolean
+      description: |
+        When enabled, the `vrc/keystream` endpoint becomes available.
+
+        When enabling Vrc for one device, all other device's Vrcs are
+        implicitely disabled.
+
+VrcKeystream:
+  type: object
+  properties:
+    seq:
+      example: 3210
+      type: integer 
+      description: |
+        Sequence number which client should increments for request.
+
+        DESIGN NOTE: Actually it's not clear that we need this. The request ID
+        already serves to prevent duplicate actions.
+    event:
+      example: HOLD
+      type: string
+      description: |
+        Event which occured on the specified key. Possibilities are:
+          - TAP -- sent if a brief (< 300 ms) press and release occurs on one or more
+             keys. If keys are tapped together (say, within 200 ms), 
+             only a single TAP event should be sent with `key` specifying both.
+          - DOUBLE_TAP (unsupported)
+          - HOLD_START -- sent after 300 ms of a key being held down.
+             If two keys are starting to be pressed within 300 ms of eachother,
+             only a single HOLD_START event should be sent.
+          - HOLD -- sent every 300 ms while keys are held.
+          - HOLD_END -- sent when a held key is released, where only the
+            released keys are specified in `key`. If some keys are still
+            held, they will continue to send `HOLD`.
+
+    key:
+      example: [1, 3]
+      type: array
+      description: |
+        list of 1-based key numbers. Must be non-empty.
+
+        In the case of a single key, an integer may be sent instead of an array.
+    hold_ms:
+      example: 1760
+      type: integer
+      description: |
+        Length of time for which key(s) has been held, in milliseconds.
+        Only provided for HOLD and HOLD_END events.
+
+        For multiple keys, this is the time since the last change
+        of keys pressed.