Merge pull request #72 from pushtheworldllc/dev

Update time synced accel packets

Author: AJ Keller

README.md

@@ -162,7 +162,7 @@ Time Syncing
 ------------
 You must be using OpenBCI firmware version 2 in order to do time syncing. After you `.connect()` and send a `.softReset()`, you can call `.usingVersionTwoFirmware()` to get a boolean response as to if you are using `v1` or `v2`.
 
-Now using firmware `v2`, the fun begins! We synchronize the Board's clock with the module's time. In firmware `v2` we leverage samples with time stamps and different time stamps and unique new features to calculate a time sync strategy. Time syncing has been verified to +/- 4ms and a test report is on the way. We are still working on the synchronize of this module and an NTP server, this is an open call for any NTP experts out there! With a global NTP server you could use several different devices and all sync to the same time server. That way you can really do some serious cloud computing!
+Now using firmware `v2`, the fun begins! We synchronize the Board's clock with the module's time. In firmware `v2` we leverage samples with time stamps and _ACKs_ from the Dongle to form a time synchronization strategy. Time syncing has been verified to +/- 4ms and a test report is on the way. We are still working on the synchronize of this module and an NTP server, this is an open call for any NTP experts out there! With a global NTP server you could use several different devices and all sync to the same time server. That way you can really do some serious cloud computing!
 
 Keep your resync interval above 50ms. While it's important to resync every couple minutes due to drifting of clocks, please do not try to sync without getting the last sync event! We can only support one sync operation at a time!
 
@@ -376,10 +376,10 @@ Board optional configurations.
   * `None` - Do not inject line noise.
 * `simulatorSampleRate` {Number} - The sample rate to use for the simulator. Simulator will set to 125 if `simulatorDaisyModuleAttached` is set `true`. However, setting this option overrides that setting and this sample rate will be used. (Default is `250`)
 * `simulatorSerialPortFailure` {Boolean} - Simulates not being able to open a serial connection. Most likely due to a OpenBCI dongle not being plugged in.
-* `sntpTimeSync` - {Boolean} Syncs the module up with an SNTP time server and uses that as single source of truth instead of local computer time. (Default `true`)
+* `sntpTimeSync` - {Boolean} Syncs the module up with an SNTP time server and uses that as single source of truth instead of local computer time. If you are running experiments on your local computer, keep this `false`. (Default `false`)
 * `sntpTimeSyncHost` - {String} The sntp server to use, can be either sntp or ntp (Defaults `pool.ntp.org`).
 * `sntpTimeSyncPort` - {Number} The port to access the sntp server (Defaults `123`)
-* `verbose` {Boolean} - Print out useful debugging events
+* `verbose` {Boolean} - Print out useful debugging events (Default `false`)
 
 **Note, we have added support for either all lowercase OR camel case for the options, use whichever style you prefer.**
 
@@ -879,6 +879,8 @@ Send the command to tell the board to start the syncing protocol. Must be connec
 
 **Example**
 
+Syncing multiple times to base the offset of the average of the four syncs.
+
 ```javascript
 var OpenBCIBoard = require('openbci').OpenBCIBoard,
     ourBoard = new OpenBCIBoard({
@@ -1068,7 +1070,7 @@ The name of the simulator port.
 
 ### LabStreamingLayer
 
-[LabStreamingLayer](https://github.com/sccn/labstreaminglayer) by SCCN is a stream management tool designed to time-synchronize multiple data streams, potentially from different sources, over a LAN network with millisecond accuracy (given configuration). 
+[LabStreamingLayer](https://github.com/sccn/labstreaminglayer) by SCCN is a stream management tool designed to time-synchronize multiple data streams, potentially from different sources, over a LAN network with millisecond accuracy (given configuration).
 
 For example, a VR display device running a Unity simulation may, using the [LSL4Unity](https://github.com/xfleckx/LSL4Unity) library, emit string markers into LSL corresponding to events of interest (For the P300 ERP, this event would be the onset of an attended, unusual noise in a pattern of commonplace ones). The computer doing data collection via the OpenBCI_NodeJS library (potentially with 4ms accuracy) would then output into an LSL stream the EEG and AUX data. LSL can then synchronize the two clocks relative to each other before inputting into a different program or toolkit, like [BCILAB](https://github.com/sccn/BCILAB) for analysis to trigger responses in the Unity display.
 

changelog.md

@@ -1,3 +1,13 @@
+# 1.2.0
+
+### New Features
+
+* Add tutorial/sample code for interfacing the module with lab streaming layer.
+
+### Breaking Changes
+
+* Fixed time synced accel to work OpenBCI_32bit_Library release candidate 5 and newer.
+
 # 1.1.0
 
 ### New Features

openBCIBoard.js

@@ -7,7 +7,7 @@ var EventEmitter = require('events').EventEmitter,
     openBCISample = require('./openBCISample'),
     k = openBCISample.k,
     openBCISimulator = require('./openBCISimulator'),
-    now = require("performance-now"),
+    now = require('performance-now'),
     Sntp = require('sntp'),
     StreamSearch = require('streamsearch'),
     bufferEqual = require('buffer-equal'),
@@ -1525,7 +1525,7 @@ function OpenBCIFactory() {
 
     /**
      * @description Send the command to tell the board to start the syncing protocol. Must be connected,
-     *      streaming and using version +2 firmware.
+     *      streaming and using at least version 2.0.0 firmware.
      *      **Note**: This functionality requires OpenBCI Firmware Version 2.0
      * @since 1.0.0
      * @returns {Promise} - Resolves if sent, rejects if not connected or using firmware verison +2.
@@ -1546,7 +1546,7 @@ function OpenBCIFactory() {
 
     /**
      * @description Send the command to tell the board to start the syncing protocol. Must be connected,
-     *      streaming and using version +2 firmware. Uses the `synced` event to ensure multiple syncs
+     *      streaming and using at least version 2.0.0 firmware. Uses the `synced` event to ensure multiple syncs
      *      don't overlap.
      *      **Note**: This functionality requires OpenBCI Firmware Version 2.0
      * @since 1.1.0
@@ -1889,7 +1889,7 @@ function OpenBCIFactory() {
                     //    n                                   n      t packet
                     //     t                                   t confirmation
                     if ((this.sync.curSyncObj.timeSyncSetPacket - this.sync.curSyncObj.timeSyncSentConfirmation) < k.OBCITimeSyncThresholdTransFailureMS) {
-                        // Estimate that 75% of the time between sent and set packet was spent on the packet making it's way from board to this point
+                        // Estimate that 75% of the time between sent and set packet was spent on the packet making its way from board to this point
                         this.sync.curSyncObj.timeTransmission = math.floor((this.sync.curSyncObj.timeSyncSetPacket - this.sync.curSyncObj.timeSyncSent) * k.OBCITimeSyncMultiplierWithSyncConf);
                         if (this.options.verbose) console.log(`Had to correct transmission time`);
                         this.sync.curSyncObj.correctedTransmissionTime = true;

openBCIConstants.js

@@ -275,9 +275,9 @@ const OBCIStreamPacketRawAuxTimeSynced   = 6; // 0110
 const OBCIStreamPacketTimeByteSize = 4;
 
 /** Time synced with accel packet */
-const OBCIAccelAxisX = 0;
-const OBCIAccelAxisY = 1;
-const OBCIAccelAxisZ = 2;
+const OBCIAccelAxisX = 7;
+const OBCIAccelAxisY = 8;
+const OBCIAccelAxisZ = 9;
 
 /** Firmware version indicator */
 const OBCIFirmwareV1 = 'v1';

openBCISample.js

@@ -776,9 +776,9 @@ function getFromTimePacketTime(dataBuf) {
 
 /**
  * @description Grabs an accel value from a raw but time synced packet. Important that this utilizes the fact that:
- *      X axis data is sent with every sampleNumber % 10 === 0
- *      Y axis data is sent with every sampleNumber % 10 === 1
- *      Z axis data is sent with every sampleNumber % 10 === 2
+ *      X axis data is sent with every sampleNumber % 10 === 7
+ *      Y axis data is sent with every sampleNumber % 10 === 8
+ *      Z axis data is sent with every sampleNumber % 10 === 9
  * @param dataBuf {Buffer} - The 33byte raw time synced accel packet
  * @param accelArray {Array} - A 3 element array that allows us to have inter packet memory of x and y axis data and emit only on the z axis packets.
  * @returns {Promise} - Fulfills with a boolean that is true only when the accel array is ready to be emitted... i.e. when this is a Z axis packet
@@ -791,15 +791,15 @@ function getFromTimePacketAccel(dataBuf, accelArray) {
         var sampleNumber = dataBuf[k.OBCIPacketPositionSampleNumber];
         switch (sampleNumber % 10) { // The accelerometer is on a 25Hz sample rate, so every ten channel samples, we can get new data
             case k.OBCIAccelAxisX:
-                accelArray[k.OBCIAccelAxisX] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
+                accelArray[0] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
                 resolve(false);
                 break;
             case k.OBCIAccelAxisY:
-                accelArray[k.OBCIAccelAxisY] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
+                accelArray[1] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
                 resolve(false);
                 break;
             case k.OBCIAccelAxisZ:
-                accelArray[k.OBCIAccelAxisZ] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
+                accelArray[2] = sampleModule.interpret16bitAsInt32(dataBuf.slice(lastBytePosition, lastBytePosition + 2)) * SCALE_FACTOR_ACCEL; // slice is not inclusive on the right
                 resolve(true);
                 break;
             default:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "openbci",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "The official Node.js SDK for the OpenBCI Biosensor Board.",
   "main": "openBCIBoard",
   "scripts": {

test/OpenBCIConstants-test.js

@@ -474,13 +474,13 @@ describe('OpenBCIConstants', function() {
     });
     describe('Time synced with accel packet',function() {
         it('X axis',function () {
-            assert.equal(0, k.OBCIAccelAxisX);
+            assert.equal(7, k.OBCIAccelAxisX);
         });
         it('Y axis',function () {
-            assert.equal(1, k.OBCIAccelAxisY);
+            assert.equal(8, k.OBCIAccelAxisY);
         });
         it('Z axis',function () {
-            assert.equal(2, k.OBCIAccelAxisZ);
+            assert.equal(9, k.OBCIAccelAxisZ);
         });
     });
     describe('Time sync useful numbers',function() {

test/OpenBCISample-test.js

@@ -259,9 +259,9 @@ describe('openBCISample',function() {
     describe('#getFromTimePacketAccel',function() {
         var packet;
 
-        it('should emit and array if z axis i.e. sampleNumber % 10 === 2', function(done) {
+        it('should emit and array if z axis i.e. sampleNumber % 10 === 9', function(done) {
             // Make a packet with a sample number that represents z axis
-            packet = openBCISample.samplePacketAccelTimeSynced(2);
+            packet = openBCISample.samplePacketAccelTimeSynced(9);
             openBCISample.getFromTimePacketAccel(packet,accelArray)
                 .then(isZAxis => {
                     // accel array ready
@@ -272,19 +272,19 @@ describe('openBCISample',function() {
                     done(err);
                 })
         });
-        it('false if sample number is not sampleNumber % 10 === 2', function(done) {
+        it(`false if sample number is not sampleNumber % 10 === ${k.OBCIAccelAxisZ}`, function(done) {
             // Make a packet that is anything but the z axis
-            packet = openBCISample.samplePacketAccelTimeSynced(0);
+            packet = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisX);
             openBCISample.getFromTimePacketAccel(packet,accelArray)
                 .then(isZAxis => {
-                    // Accel array not ready for sampleNumber % 10 === 0
+                    // Accel array not ready for sampleNumber % 10 === 7
                     isZAxis.should.equal(false);
 
-                    packet = openBCISample.samplePacketAccelTimeSynced(1);
+                    packet = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisY);
                     return openBCISample.getFromTimePacketAccel(packet,accelArray);
                 })
                 .then(isZAxis => {
-                    // Accel array not ready for sampleNumber % 10 === 1
+                    // Accel array not ready for sampleNumber % 10 === 8
                     isZAxis.should.equal(false);
 
                     packet = openBCISample.samplePacketAccelTimeSynced(34);
@@ -294,11 +294,11 @@ describe('openBCISample',function() {
                     // Accel array not ready for sampleNumber % 10 === 4
                     isZAxis.should.equal(false);
 
-                    packet = openBCISample.samplePacketAccelTimeSynced(99);
+                    packet = openBCISample.samplePacketAccelTimeSynced(100);
                     return openBCISample.getFromTimePacketAccel(packet,accelArray);
                 })
                 .then(isZAxis => {
-                    // Accel array not ready for sampleNumber % 10 === 9
+                    // Accel array not ready for sampleNumber % 10 === 0
                     isZAxis.should.equal(false);
                     done();
                 })
@@ -316,14 +316,14 @@ describe('openBCISample',function() {
         // Global array (at least it's global in practice) to store accel data between packets
         var packet1, packet2, packet3;
 
-        it('should only include accel data array on sampleNumber%10 === 2', function(done) {
+        it(`should only include accel data array on sampleNumber%10 === ${k.OBCIAccelAxisZ}`, function(done) {
             // Generate three packets, packets only get one axis value per packet
-            //  X axis data is sent with every sampleNumber % 10 === 0
-            packet1 = openBCISample.samplePacketAccelTimeSynced(0);
-            //  Y axis data is sent with every sampleNumber % 10 === 1
-            packet2 = openBCISample.samplePacketAccelTimeSynced(1);
-            //  Z axis data is sent with every sampleNumber % 10 === 2
-            packet3 = openBCISample.samplePacketAccelTimeSynced(2);
+            //  X axis data is sent with every sampleNumber % 10 === 7
+            packet1 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisX);
+            //  Y axis data is sent with every sampleNumber % 10 === 8
+            packet2 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisY);
+            //  Z axis data is sent with every sampleNumber % 10 === 9
+            packet3 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisZ);
 
             openBCISample.parsePacketTimeSyncedAccel(packet1,defaultChannelSettingsArray,0,accelArray)
                 .then(sampleObject => {
@@ -342,12 +342,12 @@ describe('openBCISample',function() {
         });
         it('should convert raw numbers into g\'s with scale factor',function(done) {
             // Generate three packets, packets only get one axis value per packet
-            //  X axis data is sent with every sampleNumber % 10 === 0
-            packet1 = openBCISample.samplePacketAccelTimeSynced(0);
-            //  Y axis data is sent with every sampleNumber % 10 === 1
-            packet2 = openBCISample.samplePacketAccelTimeSynced(1);
-            //  Z axis data is sent with every sampleNumber % 10 === 2
-            packet3 = openBCISample.samplePacketAccelTimeSynced(2);
+            //  X axis data is sent with every sampleNumber % 10 === 7
+            packet1 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisX);
+            //  Y axis data is sent with every sampleNumber % 10 === 8
+            packet2 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisY);
+            //  Z axis data is sent with every sampleNumber % 10 === 9
+            packet3 = openBCISample.samplePacketAccelTimeSynced(k.OBCIAccelAxisZ);
 
             openBCISample.parsePacketTimeSyncedAccel(packet1,defaultChannelSettingsArray,0,accelArray)
                 .then(() => {