On this site you will find:

 

Initiate

After the implementation of “How to integrate the Java Library” and “Build a sample bluetooth scanner” you can start to work with the DigipenKit and let the ErgoPen do cool things. The first thing you need to do is to initialize the DigipenKit. Before you do this you should read someting about the mask.

You have three possibilities to initiate the DigipenKit:

  1. Initialize the DigipenKit without a mask. This way the DigipenKit will choose a default mask:
    final String DEFAULT_MASK = "1101100000000000000000000011111000000000000000000000000000010000";
  2. Initialize the DigipenKit with a bytaArray mask
  3. Initialize the DigipenKit with a String

If you want to change settings (for this please read “ErgoPen for experts”) or send commands to the pen like turning it off or do a calibration, you have to initialize the class DigipenData, too. The class DigipenData uses the class DigipenKit for the initialization.

Connect

This is the code to connect to the choosen ErgoPen. You will get the BluetoothDevice for example from our sample bluetooth scanner.

To disconnect from the ErgoPen, you can choose two commands. The first posibility just disconnects the ErgoPen, but the BluetoothGatt object will be held.

The second posibility will release any resources held by the BluetoothGatt object.

The callback

The DigipenKit includes a few callback-methods to work with the data from the ErgoPen.

  1. onDigipenInformationChange(DeviceInformation deviceInformation)
    This interface changes the device information. This callback sends a DeviceInformation object. In this object you will find the battery state, the average rssi or the device name. See the comments for details:
  2. onDigipenDataTransfer(StreamData streamData, Error error)
    This interface reads the stream data from the pen. The stream data includes values from the pen’s sensors. The pen samples data at an interval of 5ms. So please consider that this could mean a lot of load right here. Which values are streamed is selected by the mask which you sent to the pen at initialization. For more information read this. In this object you will find a list with all the values send by the pen. See the comments for details:

    Please note the second object that you get right here. It is the basic java Error class. This object holds the exception, the exception trace and a manually created error explanation. The data is separated with “%#%“. A good way to implement the error objects and the stream data is first to check whether the error object is null. See the comments for details:

    Here you can see an example that shows how you should work with the stream data penDataList:
  3. onDigipenSettingsChange(int COMMAND, boolean success, String commandOutput)
    This callback gives you information about changes on the ErgoPen settings. The int COMMAND keeps information about the request that has triggered this callback. You can check the COMMAND with static fields of the class Settings as shown in the code example. The boolean success tells you if the mask-change was successful. The String commandOutput contains the value of the new mask.
  4. onDigipenCalibration(boolean isCalibratingMagnetometer, int magnetometerCalibrationProgress, boolean isCalibratingGyro, int gyroCalibrationProgress, boolean isCalibrationFinished)
    If you are in the calibration mode, the ErgoPen gives you the status of the calibration in this callback. The booleans show which sensor is being calibrated. The int shows the progress of the respective calibration. The following code example should show how you can work with it:

    If you want to learn more about the calibration, follow this link to “ErgoPen for experts”

The mask

Due to restrictions in the Bluetooth Low Energy protocol we had to minimize the data transfer between the pen and the device. Because we are working with live stream data of over 60 values we could not wrap them up in one data package. So we’ve invented the mask. The mask tells the ErgoPen what data we need.

You can have a look at all the data that the pen can send in this table.

This is how the mask works:

  1. The mask is restricted to exact 8 byte length (equal to 64 chars)
  2. The mask can contain a maximum of 10 chosen values out of the available ones
  3. Of course, the mask can not be null or empty
  4. Every item of this table represents one char of the maskString. As you see, the table is ordered by the slot number. Slot 0 represents the item x0 which is “the position of the body frame along the x-axis of global coordinate frame“. If you want to work with this value, you must choose a “1” at postion 0 (because it is slot 0) in your maskString. Move on for the 64 chars of the maskString like that.how the mask works

To change the mask, choose the method changeMask of the class Settings of the class DigipenData.

Slot Item Description Ranges
0 x0 Position of the Body frame along the X-axis of global coordinate frame. +/- 3.0 m
1 x1 Position of the Body frame along the Y-axis of global coordinate frame. +/- 3.0 m
2 x2 Position of the Body frame along the Z-axis of global coordinate frame. +/- 3.0 m
3 x3 Velocity of the Body frame along the X-axis of global coordinate frame. +/- 1.0 m/s
4 x4 Velocity of the Body frame along the Y-axis of global coordinate frame. +/- 1.0 m/s
5 x5 Velocity of the Body frame along the Z-axis of global coordinate frame. +/- 1.0 m/s
6 acX Compensated Acceleration of the Body frame along the X-axis of global coordinate frame. +/- 20.0 m/s²
7 acY Compensated Acceleration of the Body frame along the Y-axis of global coordinate frame. +/- 20.0 m/s²
8 acZ Compensated Acceleration of the Body frame along the Z-axis of global coordinate frame. +/- 20.0 m/s²
9 x9 Angular Position around the X-axis of the body frame. +/- 180.0°
10 x10 Angular Position around the Y-axis of the body frame. +/- 180.0°
11 x11 Angular Position around the Z-axis of the body frame. +/- 180.0°
12 x12 Angular Velocity around the X-axis of the body frame. +/- 180.0°/s
13 x13 Angular Velocity around the Y-axis of the body frame. +/- 180.0°/s
14 x14 Angular Velocity around the Z-axis of the body frame. +/- 180.0°/s
15 x15 Smoothed Magnetic intensity sensed against the X-axis of the body frame. +/- 2.0
16 x16 Smoothed Magnetic intensity sensed against the Y-axis of the body frame. +/- 2.0
17 x17 Smoothed Magnetic intensity sensed against the Z-axis of the body frame. +/- 2.0
18 q0 Scalar component of the first Quaternion. [qw qx qy qz] +/- 1.0
19 q1 X-element of the vector component of the first Quaternion. [qw qx qy qz] +/- 1.0
20 q2 Y-element of the vector component of the first Quaternion. [qw qx qy qz] +/- 1.0
21 q3 Z-element of the vector component of the first Quaternion. [qw qx qy qz] +/- 1.0
22 q0_2 Scalar component of the second Quaternion. [qw qx qy qz] +/- 1.0
23 q1_2 X-element of the vector component of the second Quaternion. [qw qx qy qz] +/- 1.0
24 q2_2 Y-element of the vector component of the second Quaternion. [qw qx qy qz] +/- 1.0
25 q3_2 Z-element of the vector component of the second Quaternion. [qw qx qy qz] +/- 1.0
26 pres Pressure sensor [0.0 to 4.0] Same as 59
27 fsn Proportional angular torque [0.0 , 1.0]
28 touching Touching indicator [0 or 1] 0 or 1
29 tx Position of the Tip along the X-axis of global coordinate frame. +/- 3.0 m
30 ty Position of the Tip along the Y-axis of global coordinate frame. +/- 3.0 m
31 tz Position of the Tip along the Z-axis of global coordinate frame. +/- 3.0 m
32 bx Position of the Body frame along the X-axis of global coordinate frame. +/- 3.0 m
33 by Position of the Body frame along the Y-axis of global coordinate frame. +/- 3.0 m
34 bz Position of the Body frame along the Z-axis of global coordinate frame. +/- 3.0 m
35 wx Not used. Reserved.
36 wy Not used. Reserved.
37 wz Not used. Reserved.
38 z0 Scaled linear acceleration sensed along the X-axis of the sensor frame. +/- 20.0 m/s²
39 z1 Scaled linear acceleration sensed along the Y-axis of the sensor frame. +/- 20.0 m/s²
40 z2 Scaled linear acceleration sensed along the Z-axis of the sensor frame. +/- 20.0 m/s²
41 z3 Scaled angular velocity sensed around the X-axis of the sensor frame. +/- 180.0°/s
42 z4 Scaled angular velocity sensed around the Y-axis of the sensor frame. +/- 180.0°/s
43 z5 Scaled angular velocity sensed around the Z-axis of the sensor frame. +/- 180.0°/s
44 z6 Magnetic intensity sensed against the X-axis of the sensor frame. +/- 2.0
45 z7 Magnetic intensity sensed against the Y-axis of the sensor frame. +/- 2.0
46 z8 Magnetic intensity sensed against the Z-axis of the sensor frame. +/- 2.0
47 Acc1 X Raw linear acceleration sensed along the X-axis of the front sensor frame.
48 Acc1 Y Raw linear acceleration sensed along the Y-axis of the front sensor frame.
49 Acc1 Z Raw linear acceleration sensed along the Z-axis of the front sensor frame.
50 Acc2 X Raw linear acceleration sensed along the X-axis of the rear sensor frame.
51 Acc2 Y Raw linear acceleration sensed along the Y-axis of the rear sensor frame.
52 Acc2 Z Raw linear acceleration sensed along the Z-axis of the rear sensor frame.
53 Gyro X Raw angular velocity sensed around the X-axis of the sensor frame.
54 Gyro Y Raw angular velocity sensed around the Y-axis of the sensor frame.
55 Gyro Z Raw angular velocity sensed around the Z-axis of the sensor frame.
56 Magn X Raw magnetic intensity sensed against the X-axis of the sensor frame.
57 Magn Y Raw magnetic intensity sensed against the Y-axis of the sensor frame.
58 Magn Z Raw magnetic intensity sensed against the Z-axis of the sensor frame.
59 Force Raw pressure sensor [0 to 4096] [0 , 4096]
60 Time Time counter.
61 n/a not used
62 n/a not used
63 n/a not used