feat: CORE-5635 - support device orientation

src/instance.js

@@ -65,6 +65,16 @@ const split = require('split')
  * @property {integer} offRateMicrocents - The amount per second, in microcents (USD), that this instance charges to be stored.
  */
 
+/**
+ * @typedef {number} RotationType
+ *
+ * Valid values are 1-4 where each number corresponds to a device orientation.
+ * 1. Portrait: The device is held upright, with the top edge at the top.
+ * 2. Portrait Vertically Inverted (Upside-Down): The device is held upright, but with the top edge at the bottom.
+ * 3. Landscape (Top of Device to the Left): The device is turned sideways with the top edge facing left.
+ * 4. Landscape (Top of Device to the Right): The device is turned sideways with the top edge facing right.
+ */
+
 /**
  * Instances of this class are returned from {@link Project#instances}, {@link
  * Project#getInstance}, and {@link Project#createInstance}. They should not be
@@ -147,6 +157,13 @@ class Instance extends EventEmitter {
     return this.info.type
   }
 
+  /**
+   * The instance orientation
+   */
+  get orientation() {
+    return this.info.orientation
+  }
+
   /**
    * The pending task that is being requested by the user and is being executed by the backend.
    * This field is null when no tasks are pending. The returned object has two fields: name and options.
@@ -239,6 +256,21 @@ class Instance extends EventEmitter {
     })
   }
 
+  /**
+   * Change device orientation.
+   * @param {RotationType} rotation - The new rotation for the instance.
+   * @example await instance.rotate(1);
+   */
+  async rotate(rotation) {
+    await this._fetch('/rotate', {
+      method: 'POST',
+      json: {
+        orientation: rotation
+      },
+      response: 'raw'
+    })
+  }
+
   /**
    * Get peripheral/sensor data
    * @return {Promise<PeripheralData>}