Dictation API

README.md

@@ -13,7 +13,7 @@ Pebble.js applications run on your phone. They have access to all the resources
 
 ## Getting Started
 
- * In CloudPebble
+ * In CloudPebble 
 
    The easiest way to use Pebble.js is in [CloudPebble](https://cloudpebble.net). Select the 'Pebble.js' project type when creating a new project.
 
@@ -146,16 +146,6 @@ wind.add(textfield);
 wind.show();
 ````
 
-## Examples
-
-Coming Soon!
-
-## Acknowledgements
-
-Pebble.js started as [Simply.JS](http://simplyjs.io), a project by [Meiguro](http://github.com/meiguro). It is now part of the Pebble SDK and supported by Pebble. Contact [[email protected]](mailto:[email protected]) with any questions!
-
-This documentation uses [Flatdoc](http://ricostacruz.com/flatdoc/#flatdoc).
-
 # API Reference
 
 ## Global namespace
@@ -407,14 +397,6 @@ You can use the accelerometer in two different ways:
 var Accel = require('ui/accel');
 ````
 
-#### Accel.init()
-
-Before you can use the accelerometer, you must call `Accel.init()`.
-
-````js
-Accel.init();
-````
-
 #### Accel.config(accelConfig)
 
 This function configures the accelerometer `data` events to your liking. The `tap` event requires no configuration for use. Configuring the accelerometer is a very error prone process, so it is recommended to not configure the accelerometer and use `data` events with the default configuration without calling `Accel.config`.
@@ -494,6 +476,34 @@ wind.on('accelData', function(e) {
 });
 ````
 
+### Voice
+
+The `Voice` module allows you to interact with Pebble's dictation API on supported platforms (Basalt and Chalk).
+
+````js
+var Voice = require('ui/voice');
+````
+
+#### Voice.startDictationSession(callback)
+
+This function starts the dictation UI, and invokes the callback upon completion. The callback is invoked with an event with the following fields:
+
+* `status`: The [DictationSessionStatus](https://developer.getpebble.com/docs/c/Foundation/Dictation/#DictationSessionStatus) (or -1 if the platform is not supported).
+* `transcription`: The transcribed string
+
+```js
+Voice.startDictationSession(function(e) {
+  if (e.status != 0) {
+    // if there was an error
+    console.log('Error: ' + e.status);
+    return;
+  }
+
+  // Log the result
+  console.log('Success: ' + e.transcription);
+});
+```
+
 ### Window
 
 `Window` is the basic building block in your Pebble.js application. All windows share some common properties and methods.
@@ -1338,3 +1348,13 @@ For more information, see [Vector2 in the three.js reference documentation][thre
 [Text]: #text
 [TimeText]: #timetext
 [three.js Vector2]: http://threejs.org/docs/#Reference/Math/Vector2
+
+## Examples
+
+Coming Soon!
+
+## Acknowledgements
+
+Pebble.js started as [Simply.JS](http://simplyjs.io), a project by [Meiguro](http://github.com/meiguro). It is now part of the Pebble SDK and supported by Pebble. Contact [[email protected]](mailto:[email protected]) with any questions!
+
+This documentation uses [Flatdoc](http://ricostacruz.com/flatdoc/#flatdoc).

src/js/lib/struct.js

@@ -139,6 +139,7 @@ struct.prototype._prevField = function(field) {
 struct.prototype._makeAccessor = function(field) {
   this[field.name] = function(value) {
     var type = field.type;
+
     if (field.dynamic) {
       var prevField = this._prevField(field);
       if (prevField === undefined) {

src/js/ui/simply-pebble.js

@@ -5,6 +5,7 @@ var Wakeup = require('wakeup');
 var Timeline = require('timeline');
 var Resource = require('ui/resource');
 var Accel = require('ui/accel');
+var Voice = require('ui/voice');
 var ImageService = require('ui/imageservice');
 var WindowStack = require('ui/windowstack');
 var Window = require('ui/window');
@@ -764,6 +765,21 @@ var ElementAnimateDonePacket = new struct([
   ['uint32', 'id'],
 ]);
 
+var NumCommandsPacket = new struct([
+  [Packet, 'packet'],
+  ['uint32', 'id'],
+]);
+
+var VoiceDictationStartPacket = new struct([
+  [Packet, 'packet'],
+]);
+
+var VoiceDictationDataPacket = new struct([
+  [Packet, 'packet'],
+  ['int8', 'status'],
+  ['cstring', 'transcription'],
+]);
+
 var CommandPackets = [
   Packet,
   SegmentPacket,
@@ -815,6 +831,9 @@ var CommandPackets = [
   ElementImagePacket,
   ElementAnimatePacket,
   ElementAnimateDonePacket,
+  NumCommandsPacket,
+  VoiceDictationStartPacket,
+  VoiceDictationDataPacket,
 ];
 
 var accelAxes = [
@@ -1113,6 +1132,35 @@ SimplyPebble.accelConfig = function(def) {
   SimplyPebble.sendPacket(AccelConfigPacket.prop(def));
 };
 
+SimplyPebble.voiceDictationSession = function(callback) {
+  // If there's a transcription in progress
+  if (SimplyPebble.dictationCallback) {
+    callback( { 'status': -1, 'transcription': null } );
+    return;
+  }
+
+  // Grab the current window to re-show once we're done
+  SimplyPebble.window = WindowStack.top();
+
+  // Set the callback and send the packet
+  SimplyPebble.dictationCallback = callback;
+  SimplyPebble.sendPacket(VoiceDictationStartPacket);
+}
+
+SimplyPebble.onVoiceData = function(packet) {
+  if (!SimplyPebble.dictationCallback) {
+    // Something bad happened
+    console.log("No callback specified for dictation session");
+  } else {
+    // invoke and clear the callback
+    SimplyPebble.dictationCallback( { 'status': packet.status(), 'transcription': packet.transcription() } );
+    SimplyPebble.dictationCallback = null;
+  }
+
+  // show the top window to re-register handlers, etc. 
+  SimplyPebble.window.show();
+}
+
 SimplyPebble.menuClear = function() {
   SimplyPebble.sendPacket(MenuClearPacket);
 };
@@ -1381,11 +1429,15 @@ SimplyPebble.onPacket = function(buffer, offset) {
     case ElementAnimateDonePacket:
       StageElement.emitAnimateDone(packet.id());
       break;
+    case VoiceDictationDataPacket:
+      SimplyPebble.onVoiceData(packet);
+      break;
   }
 };
 
 SimplyPebble.onAppMessage = function(e) {
   var data = e.payload[0];
+
   Packet._view = toArrayBuffer(data);
 
   var offset = 0;

src/js/ui/voice.js

@@ -0,0 +1,9 @@
+var simply = require('ui/simply');
+
+var Voice = {};
+
+Voice.startDictationSession = function(e) {
+  simply.impl.voiceDictationSession(e);
+};
+
+module.exports = Voice;

src/simply/simply.c

@@ -9,12 +9,14 @@
 #include "simply_ui.h"
 #include "simply_window_stack.h"
 #include "simply_wakeup.h"
+#include "simply_voice.h"
 
 #include <pebble.h>
 
 Simply *simply_init(void) {
   Simply *simply = malloc(sizeof(*simply));
   simply->accel = simply_accel_create(simply);
+  simply->voice = simply_voice_create(simply);
   simply->res = simply_res_create(simply);
   simply->splash = simply_splash_create(simply);
   simply->stage = simply_stage_create(simply);
@@ -39,5 +41,6 @@ void simply_deinit(Simply *simply) {
   simply_stage_destroy(simply->stage);
   simply_res_destroy(simply->res);
   simply_accel_destroy(simply->accel);
+  simply_voice_destroy(simply->voice);
   free(simply);
 }

src/simply/simply.h

@@ -6,6 +6,7 @@ typedef struct Simply Simply;
 
 struct Simply {
   struct SimplyAccel *accel;
+  struct SimplyVoice *voice;
   struct SimplyRes *res;
   struct SimplyMsg *msg;
   struct SimplyWindowStack *window_stack;

src/simply/simply_msg.c

@@ -1,6 +1,7 @@
 #include "simply_msg.h"
 
 #include "simply_accel.h"
+#include "simply_voice.h"
 #include "simply_res.h"
 #include "simply_stage.h"
 #include "simply_menu.h"
@@ -22,7 +23,7 @@
 
 static const size_t APP_MSG_SIZE_INBOUND = 2044;
 
-static const size_t APP_MSG_SIZE_OUTBOUND = 512;
+static const size_t APP_MSG_SIZE_OUTBOUND = 1024;
 
 typedef enum VibeType VibeType;
 
@@ -201,6 +202,7 @@ static void handle_packet(Simply *simply, Packet *packet) {
   if (simply_window_handle_packet(simply, packet)) { return; }
   if (simply_ui_handle_packet(simply, packet)) { return; }
   if (simply_accel_handle_packet(simply, packet)) { return; }
+  if (simply_voice_handle_packet(simply, packet)) { return; }
   if (simply_menu_handle_packet(simply, packet)) { return; }
   if (simply_stage_handle_packet(simply, packet)) { return; }
 }

src/simply/simply_msg_commands.h

@@ -53,4 +53,6 @@ enum Command {
   CommandElementAnimate,
   CommandElementAnimateDone,
   NumCommands,
+  CommandVoiceStart,
+  CommandVoiceData,
 };

src/simply/simply_voice.c

@@ -0,0 +1,100 @@
+#include "simply_voice.h"
+
+#include "simply_msg.h"
+
+#include "simply.h"
+
+#include <pebble.h>
+
+typedef struct VoiceDataPacket VoiceDataPacket;
+
+struct __attribute__((__packed__)) VoiceDataPacket {
+  Packet packet;
+  int8_t status;
+  char result[SIMPLY_VOICE_BUFFER_LENGTH];
+};
+
+static SimplyVoice *s_voice;
+
+static bool send_voice_data(int status, char *transcription) {
+  VoiceDataPacket packet = {
+    .packet.type = CommandVoiceData,
+    .packet.length = sizeof(packet),
+    .status = (uint8_t) status,
+  };
+  snprintf(packet.result, sizeof(packet.result), "%s", transcription);
+
+  return simply_msg_send_packet(&packet.packet);
+}
+
+#ifndef PBL_SDK_2
+// Define a callback for the dictation session
+static void dictation_session_callback(DictationSession *session, DictationSessionStatus status, char *transcription, void *context) {
+  s_voice->inProgress = false;
+
+  // Send the result
+  send_voice_data(status, transcription);
+}
+#endif
+
+static void timer_callback_start_dictation(void *data) {
+  dictation_session_start(s_voice->session);
+}
+
+
+static void handle_voice_start_packet(Simply *simply, Packet *data) {
+  #ifdef PBL_SDK_2
+  // send an immediate reply if we don't support voice
+  send_voice_data(-1, "");
+  #else
+
+  // Send an immediate response if there's already a dictation session in progress
+  if (s_voice->inProgress) {
+    send_voice_data(-1, "");
+    return;
+  }
+
+  // Otherwise, start the timer as soon as possible
+  // (we start a timer so we can return true as quickly as possible)
+  s_voice->inProgress = true;
+  s_voice->timer = app_timer_register(0, timer_callback_start_dictation, NULL);
+  #endif
+}
+
+bool simply_voice_handle_packet(Simply *simply, Packet *packet) {
+  switch (packet->type) {
+    case CommandVoiceStart:
+      handle_voice_start_packet(simply, packet);
+      return true;
+  }
+
+  return false;
+}
+
+SimplyVoice *simply_voice_create(Simply *simply) {
+  if(s_voice) {
+    return s_voice;
+  }
+
+  SimplyVoice *self = malloc(sizeof(*self));
+  *self = (SimplyVoice) {
+    .simply = simply,
+    .inProgress = false,
+  };
+
+  #ifndef PBL_SDK_2
+  self->session = dictation_session_create(SIMPLY_VOICE_BUFFER_LENGTH, dictation_session_callback, NULL),
+  #endif
+
+  s_voice = self;
+  return self;
+}
+
+void simply_voice_destroy(SimplyVoice *self) {
+  if (!self) {
+    return;
+  }
+
+  free(self);
+  s_voice = NULL;
+}

src/simply/simply_voice.h

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "simply_msg.h"
+#include "simply.h"
+
+#include <pebble.h>
+
+#define SIMPLY_VOICE_BUFFER_LENGTH 512
+
+#ifdef PBL_SDK_2
+typedef struct DictationSession DictationSession;
+typedef struct DictationSessionStatus DictationSessionStatus;
+void dictation_session_start(DictationSession *session);
+#endif
+
+typedef struct SimplyVoice SimplyVoice;
+
+struct SimplyVoice {
+  Simply *simply;
+  DictationSession *session;
+  AppTimer *timer;
+
+  bool inProgress;
+};
+
+SimplyVoice *simply_voice_create(Simply *simply);
+void simply_voice_destroy(SimplyVoice *self);
+
+bool simply_voice_handle_packet(Simply *simply, Packet *packet);