Skip to content

Commit

Permalink
Merge pull request #72 from pushtheworldllc/dev
Browse files Browse the repository at this point in the history 
Update time synced accel packets
  • Loading branch information
AJ Keller authored Aug 4, 2016
2 parents 9bd1121 + 6cbf99e commit 6cf5e99
Show file tree
Hide file tree
Showing 8 changed files with 55 additions and 43 deletions.
10 changes: 6 additions & 4 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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!

Expand Down Expand Up @@ -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.**
Expand Down Expand Up @@ -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({
Expand Down Expand Up @@ -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.
Expand Down
10 changes: 10 additions & 0 deletions changelog.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 4 additions & 4 deletions openBCIBoard.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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'),
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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;
Expand Down
6 changes: 3 additions & 3 deletions openBCIConstants.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
12 changes: 6 additions & 6 deletions openBCISample.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
6 changes: 3 additions & 3 deletions test/OpenBCIConstants-test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down
44 changes: 22 additions & 22 deletions test/OpenBCISample-test.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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);
Expand All @@ -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();
})
Expand All @@ -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 => {
Expand All @@ -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(() => {
Expand Down

0 comments on commit 6cf5e99

Please sign in to comment.