sensel / sensel-api

Sensel API for communicating with Sensel devices.

Sensel API

The Sensel API allows users to communicate with Sensel devices.

Sensel API Primer

Sensel Lib Documentation

Sensel Decompress Lib Documentation

Apple Silicon Support

There are currently no libraries compiled for Apple Silicon.

Getting Started

Before getting started with this API, make sure your device's firmware is up to date. Go to Sensel's Start Page to get the latest version of the SenselApp and update your device.

To run the examples, first install the Sensel libraries found in sensel-install. After installing the libraries, you can open one of the Sensel source examples (C, Python and C#).

The source for the central Sensel library can be found in sensel-lib. This includes all of the necessary functions to communicate with Sensel devices except for force frame decompression. More information can be found below.

sensel-install

The sensel-install directory contains installers for Windows, Mac and Linux that places Sensel libraries and headers into the appropriate directory for each operating system.

There are two libraries installed on each operating system. LibSensel contains the core functionality for communicating with Sensel devices. LibSenselDecompress allows you to read and decompress force frames from Sensel devices. We provide the source for LibSensel in the sensel-lib directory, which is covered under the MIT License, and can be compiled to not link or depend on LibSenselDecompress.

Windows:

SenselLibWin.exe installs the libraries and headers into C:\Program Files\Sensel\Sense Lib\ with the following directories: include for the headers, x86 for 32-bit compiled .dll and .lib, and x64 for 64-bit compiled .dll and .lib. Each test should recognize whether the process being run is 32-bit or 64-bit and reference the appropriate libraries.

Mac:

SenselLibMac.pkg installs the libraries into /usr/local/lib and the headers into /usr/local/include. The installer only includes a 64-bit version of the libraries. If a 32-bit version is required, then see the sensel-lib section below to see how to compile the core library.

Linux

senselliblinux.deb installs the libraries into /usr/lib and the headers into /usr/include. The installer only includes a 64-bit version of the libraries. If a 32-bit version is required, then see the sensel-lib section below to see how to compile the core library.

sensel-examples

The sensel-examples directory includes examples for C, C#, and Python to demonstrate how to use the Sensel libraries for each language.

Sensel Examples

example-1-hello-sensel

Example 1 demonstrates how to find Sensel devices, open the device, and request information about from the device.

example-2-contacts

Example 2 demonstrates how to connect to a Sensel Device, start scanning for contacts, and read a frame of data for contacts.

example-3-forces

Example 3 demonstrates how to connect to a Sensel Device, start scanning for forces, and read a frame of force data. In this example, all the forces are being summed to report the total force.

example-4-multi

Example 4 demonstrates how to connect to multiple Sensel Devices, start scanning for contacts, and read a frame of data for contacts.

sensel-lib

The sensel-lib directory contains the source for the core Sensel library. LibSensel is covered under the MIT license. LibSensel contains the main functionality for communicating with Sensel devices, but does not include force frame decompression, which is contained in LibSenselDecompress. Both libraries are included in the installers found in sensel-install, but LibSensel can be recompiled to be a standalone library (no dependencies on LibSenselDecompress) or to replace the existing LibSensel and support force frames.

Build without Forces (Standalone)

The sensel-lib directory builds without forces by default. This can be done in Visual Studio for Windows, xCode for Mac and the Makefile for Linux.

If you want to test this new library then you can either install the library into the appropriate install directory for each operating system or build the tests to reference a library in the same directory as the test.

Build with Forces

To build the LibSensel with force, simply define SENSEL_PRESSURE. This will build LibSensel with references to LibSenselDecompress.

To install this library, replace the existing library and headers, making sure to leave LibSenselDecompress and sensel_decompress.h to ensure proper force frame functionality.

sensel-api's Issues

Morph freeze-up when using Sensel API to get force data

We came across a couple of issues concerning the Python Sensel API while trying to get force data using the Morph. The Morph would constantly freeze-up and we wouldn't be able to move it around and use it as a trackpad when calling from within PsychoPy. However, using the Sensel App the Morph worked fine. So, we came to the conclusion that it had to be the API. @nyboer @AlexSensel

Are there ideas for solutions that you could provide to remedy this issue? This is critical to the progression of our project.

Thank you,
M

can't build 32-bit with pressure

Trying to build 32-bit sensel lib for raspberry pi 3 (armv7l)

I followed the readme instructions in the read me, so i did:

• I defined #define SENSEL_PRESSURE 1 in sensel.c
• I ran make
• I got an error saying sensel_decompress.h can't be found
• i found that file inside the debian package, copied it to the src folder, ran make again, got this:

pi@MO:~/Development/sensel-api/sensel-lib $ make
rm -f src/*.o
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel.o src/sensel.c
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel_register.o src/sensel_register.c
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel_serial_linux.o src/sensel_serial_linux.c
mkdir -p build/release/nopressure//obj
mv src/sensel.o src/sensel_register.o src/sensel_serial_linux.o build/release/nopressure//obj
gcc -shared -Wl,-soname,libsensel.so -o build/release/nopressure/libsensel.so build/release/nopressure//obj/sensel.o build/release/nopressure//obj/sensel_register.o build/release/nopressure//obj/sensel_serial_linux.o 
strip build/release/nopressure/libsensel.so

-here is the build folder that was created:

-tried to execute libsensel.so on the pi, and got this error:

pi@MO:~/Development/sensel-api/sensel-lib/build/release/nopressure $ ./libsensel.so 
Segmentation fault

what now?

building C SenselContacts x86 error

I can build HelloSensel both x64 and x86
However, SenselContacts will only build as x64
the error given:
Severity Code Description Project File Line Suppression State
Error C2440 'function': cannot convert from 'void *(__cdecl *)()' to 'LPTHREAD_START_ROUTINE' SenselContacts C:\mypath\sensel-api\sensel-examples\sensel-c\example-2-contacts\src\main.c 77

Detected force decaying over time

While experimenting with the API and samples, I have noticed that the detected forces decay with time. During my tests, when leaving an object on the board, I see the reported forces going down until reaching a stable value which is usually close to zero. The same happens if I repeatedly place the same object on the board. Strangely enough, even when using the same object, the forces reported on contact can greatly vary.

Is this the expected behavior, or do I need to perform some form of calibration?

Thanks!

missing LibSenselDecompress on arch64-based OSX-machines

I tried to build the sensel API on my osx machine, however, the dynamically linked library LibSenselDecompress seems to not be available in a native format. See also discussion on the forum.

Any help would be much appreciated.

Publish Sensel to PyPi

The python wrapper for the API could be published to PyPi as a wheel which would be much more convenient than manually copying the file around. It would allow python developers to install the sensel-lib, then just pip install sensel to get started developing.

There's a pretty clear guide to follow to do so: https://packaging.python.org/tutorials/distributing-packages/

handle multiple morphs in contacts example, possible bug causing missing CONTACT_ENDs

See the pull request I just submitted, which adds support for multiple morphs as well as making it easy to demonstrate a possible bug I've found. Quick taps of three fingers will sometimes/often miss sending the CONTACT_ENDS for all of the contacts. Seems to happen even with one Morph, though most of my testing is with 4 Morphs. I changed the example to print a little more info (like the contact state, which reveals the bug), as well as turn LEDs on/off (which makes it easy to see when you've hit the bug). I also changed it so that it runs forever until you hit control-C, which makes the example a lot more useful interactively.

conflicting declaration typedef long long unsigned int uint64

As comments in sensel_types.h mention, some of those typedefs conflict with external code. In my case, uint64 and int64 conflicted with OpenCV 3.3.1's core/hal/interface.h.

Would be nice to have a way to eliminate informative stdout messages, and get error information programmatically

Two related issues.

Currently, senselGetDeviceList (and possibly other APIs) send informative messages to stdout. It would be nice to be able to turn those off, for a variety of reasons (e.g. running inside a plugin, or utilities that want to be silent except for errors).

Error messages are currently sent to stdout, and in some cases different errors producing the same API return value (SENSEL_ERROR) without a way for the caller to find out which error occurred. At the very least it would be nice for there to be a few other ERROR types, and ideally the error messages themselves should be retrievable programmatically rather than being unconditionally printed.

Sensel C API on iOS?

I am able to build the sensel API for iOS and connect the Sensel Morph via bluetooh and with a wired connection, but the API is unable to opendir("\dev\") to find the device.

Here is a permalink to the relevant line:
https://github.com/sensel/sensel-api/blob/0b117e17c0c9c2eaf62366892dec4773e1a73de0/sensel-lib/src/sensel_serial_linux.c#L303

I assume the path is either different on iOS or is safeguarded by the OS itself. Is it at all possible to access the Sensel Morph on iOS? Since the notes application, the OS, and other MIDI applications respond to Sensel input, I would think there would be some way.

Support for MIDI Polyphonic Expression (MPE)

MPE is a method of using MIDI which enables multidimensional controllers to control multiple parameters of every note within MPE-compatible software. [..] In normal MIDI, channel-wide messages (such as pitch bend) are applied to all notes being played on a single channel. In MPE, each note is assigned its own channel so that those messages can be applied to each note individually.

Links:

• https://www.midi.org/articles/midi-polyphonic-expression-mpe
• https://support.roli.com/article/what-is-mpe/
• https://github.com/WeAreROLI/mpejs
• https://juce.com/doc/tutorial_mpe_introduction
• https://juce.com/doc/group__juce__audio__basics-mpe

Link to serial port rules file for Linux users

Hi!
I was struggling to get the API working on Linux until I found this forum post and the accompanying serial port rules file: https://forum.sensel.com/t/morph-update-version-0-16-overlay-designer-beta-morph-settings-no-overlay-mpe-updates-xyz-midi-and-linux/315

Maybe it would be a good idea to include the rules file here somewhere, or at least a link to it in the README under the Linux heading?

reading overlay identifiers via API

Sorry if I should have overlooked it, couldn't find a way how to read the magnetic overlay identifiers via API on first sight though. Is this already possible?
Hopefully the overlay markers are available in the store soon, so we can build our own marked overlays!

delta_x and delta_y arbitrary

I am getting unreliable data for delta_x and delta_y.
Sometimes when I start my application the deltas just stay 0. Other times I am getting one delta as always 0, and the other one as a garbage value. And the third variant is where I get garbage values for both deltas. (The state between the three variants stays the same until I restart the application. Which variant I get seems to be randomly determined at program start).

Here two example outputs of read contacts vs corrected contacts (where I calculate the deltas myself by remembering the touch per id from previous frames):

case where delta_x stays always 0 and delta_y is garbage:
mec::SinglePanel::readTouches (corrected deltas): (x: 119.734,y:71.8008,dx:4.01172,dy:0.152344)
mec::SinglePanel::readTouches: (x: 119.734,y:71.8008,dx:0,dy:1.83705e-40,state:CONTACT_MOVE)

case where both delta_x and delta_y always stay at 0:
mec::SinglePanel::readTouches (corrected deltas): (x: 152.293,y:61.9453,dx:2.16016,dy:0.539062)
mec::SinglePanel::readTouches: (x: 152.293,y:61.9453,dx:0,dy:0,state:CONTACT_MOVE)

snippet of the code that reads the contacts:
bool frameRetrievedState = senselGetFrame(handle_, frameData_);
for(int current_contact = 0; current_contact < frameData_->n_contacts; ++current_contact) {
unsigned int state = frameData_->contacts[current_contact].state;
float x = frameData_->contacts[current_contact].x_pos;
float x_delta = frameData_->contacts[current_contact].delta_x;
float y = frameData_->contacts[current_contact].y_pos;
float y_delta = frameData_->contacts[current_contact].delta_y;
float z = frameData_->contacts[current_contact].total_force;
float z_delta = frameData_->contacts[current_contact].delta_force;

C and CS examples compiled with Visual Studio 2015 won't run

Hello,

I have installed the libraries and tried to compile the examples using Visual Studio 2015 (Community Edition) under Windows 10 Pro.

The compilation is successful but when I launch any .exe, a window seem to appear but disappears immediately, even before anything can be displayed and read.

What's wrong?

Can't get frame rate

Hello,

I am trying to get the current frame rate using this code:
senselGetMaxFrameRate(handle, unsigned short val)
However there is a red wavy underline under the word "unsigned" displayed by VS2015. If I put the mouse pointer there I have a "expression expected" popup. The compiler reports a syntax error. What's wrong?

Do senselGetScanDetail and senselSetScanDetail function correctly?

Hello,

I try to change the scan detail with function senselSetScanDetail(). I have tried all possible values ( SCAN_DETAIL_HIGH, SCAN_DETAIL_MEDIUM, SCAN_DETAIL_LOW). Whatever the value used, I get a Sensel_OK.

However if I use the senselGetScanDetail() function afterwards, I always get the same value (1, that is SCAN_DETAIL_MEDIUM).

What's wrong?

Building libsensel for Bela (BeagleBoard)

Hello,

I am attempting to create a demo of Sensel and Bela, the open source hardware and software platform for low latency embedded musical instrument design.

The 32-bit .deb does not work on Bela because the BeagleBoard has armhf hard float architecture (https://wiki.debian.org/ArmHardFloatPort):

root@Bela ~/Bela/sensel/sensel-api/sensel-install$ sudo dpkg -i senselliblinux0.8.2-32bit.deb
dpkg: error processing archive senselliblinux0.8.2-32bit.deb (--install):
 package architecture (i386) does not match system (armhf)
Errors were encountered while processing:
 senselliblinux0.8.2-32bit.deb

I have tried to build the library manually using this guide: http://blog.bela.io/2017/01/04/using-an-external-library-with-bela/

Since I wanted to build with forces (https://github.com/sensel/sensel-api#build-with-forces - this section of the readme is difficult to understand), the first problem is described by @batchku (#8), that you do not include sensel_decompress.h anywhere in this repo apart from inside the pre-built installers. I did what they did and took it from inside senselliblinux0.8.2-32bit.deb and defined SENSEL_PRESSURE = 1 in sensel.c.

Then the make output is:

root@bela ~/Bela/sensel/sensel-api/sensel-lib$ make
rm -f src/*.o
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel.o src/sensel.c
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel_register.o src/sensel_register.c
gcc -c -std=c99 -Wall -Werror -fPIC -fvisibility=hidden -Isrc/ -DSENSEL_EXPORTS  -O2   -c -o src/sensel_serial_linux.o src/sensel_serial_linux.c
mkdir -p build/release/nopressure//obj
mv src/sensel.o src/sensel_register.o src/sensel_serial_linux.o build/release/nopressure//obj
gcc -shared -Wl,-soname,libsensel.so -o build/release/nopressure/libsensel.so build/release/nopressure//obj/sensel.o build/release/nopressure//obj/sensel_register.o build/release/nopressure//obj/sensel_serial_linux.o
strip build/release/nopressure/libsensel.so

I can't tell if it's outputting to /nopressure/ because it is failing to include sensel_decompress.h or not.

I moved the resulting libsensel.so to /usr/lib and tried to run an example Bela project with the custom make flags: CFLAGS=-I/root/Bela/sensel/sensel-lib/src;LDFLAGS=-L/root/Bela/sensel/sensel-lib/build/release/nopressure/libsensel.so;LDLIBS=-lsensel

However, this project will not run:

Linking...
/usr/lib/gcc/arm-linux-gnueabihf/4.9/../../../../lib/libsensel.so: undefined reference to `senselFreeDecompressionHandle'
/usr/lib/gcc/arm-linux-gnueabihf/4.9/../../../../lib/libsensel.so: undefined reference to `senselDecompressFrame'
/usr/lib/gcc/arm-linux-gnueabihf/4.9/../../../../lib/libsensel.so: undefined reference to `senselInitDecompressionHandle'
/usr/lib/gcc/arm-linux-gnueabihf/4.9/../../../../lib/libsensel.so: undefined reference to `senselDecompressionTriggerDetailChange'
clang-3.8: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [/root/Bela/projects/sensel/sensel] Error 1Bela stopped

To me it seems like libsensel.so is not using sensel_decompress.h correctly. Help appreciated!

senselSetLEDBrightness: strange LED behavior

I'm running the contacts example and the LEDs seem to light up for only one frame after every call to senselSetLEDBrightness, then immediately turning off.

Firmware version: 0.14.116 (this is the latest one as of now)

As a sanity check, I changed these lines to the following, to make sure the brightness was actually set

unsigned short brightness;
senselGetLEDBrightness(handle, frame->contacts[c].id, &brightness);

unsigned int state = frame->contacts[c].state;
fprintf(stdout, "Contact ID: %d State: %s B: %d \n", frame->contacts[c].id, CONTACT_STATE_STRING[state], brightness);

also if I set the brightness to 10 or below, it doesn't light up at all

setting brightness to a low number down to 11 would make the LEDs stay on, but make them appear to blink (at a slower rate the more contacts there are)