sensel.h

Introduction

Functions

senselAllocateFrameData

senselClose

senselFreeFrameData

senselGetBufferControl

senselGetContactsEnableBlobMerge

senselGetContactsMask

senselGetContactsMinForce

senselGetDeviceList

senselGetDynamicBaselineEnabled(SENSEL_HANDLE, unsigned char *)

senselGetFirmwareInfo

senselGetFrame

senselGetFrameContent

senselGetLEDBrightness

senselGetMaxFrameRate

senselGetMaxLEDBrightness

senselGetNumAvailableFrames

senselGetNumAvailableLEDs

senselGetPowerButtonPressed

senselGetScanDetail

senselGetScanMode

senselGetSensorInfo

senselGetSupportedFrameContent

senselOpen

senselOpenDeviceByComPort

senselOpenDeviceByID

senselOpenDeviceBySerialNum

senselReadReg

senselReadRegVS

senselReadSensor

senselSetBufferControl

senselSetContactsEnableBlobMerge

senselSetContactsMask

senselSetContactsMinForce

senselSetDynamicBaselineEnabled(SENSEL_HANDLE, unsigned char)

senselSetFrameContent

senselSetLEDBrightness

senselSetMaxFrameRate

senselSetScanDetail

senselSetScanMode

senselSoftReset

senselStartScanning

senselStopScanning

senselWriteReg

senselWriteRegVS

senselAllocateFrameData

SENSEL_API SenselStatus WINAPI senselAllocateFrameData(
    SENSEL_HANDLE handle,
    SenselFrameData **data);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Allocates a FrameData and initializes all buffers according to device capabilities.

senselClose

SENSEL_API SenselStatus WINAPI senselClose(
    SENSEL_HANDLE handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Closes the device associated with handle and frees all memory.

senselFreeFrameData

SENSEL_API SenselStatus WINAPI senselFreeFrameData(
    SENSEL_HANDLE handle,
    SenselFrameData *data);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Frees all memory allocated to FrameData including the FrameData itself.

senselGetBufferControl

SENSEL_API SenselStatus WINAPI senselGetBufferControl(
    SENSEL_HANDLE handle,
    unsigned char *num);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Gets the number of frame buffers the device should store internaly.

senselGetContactsEnableBlobMerge

SENSEL_API SenselStatus WINAPI senselGetContactsEnableBlobMerge(
    SENSEL_HANDLE handle,
    unsigned char *val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Get contact blob merging setting

senselGetContactsMask

SENSEL_API SenselStatus WINAPI senselGetContactsMask(
    SENSEL_HANDLE handle,
    unsigned char *mask);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Gets the current contact mask setting for the device

senselGetContactsMinForce

SENSEL_API SenselStatus WINAPI senselGetContactsMinForce(
    SENSEL_HANDLE handle,
    unsigned short *val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Gets the minimum force a contact needs to have to be reported

senselGetDeviceList

SENSEL_API SenselStatus WINAPI senselGetDeviceList(
    SenselDeviceList *list);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Scans for all availale sensel devices and populates list accordingly

senselGetDynamicBaselineEnabled(SENSEL_HANDLE, unsigned char *)

SENSEL_API SenselStatus WINAPI senselGetDynamicBaselineEnabled(
    SENSEL_HANDLE handle,
    unsigned char *val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Returns state of dynamic baseline enabled flag

senselGetFirmwareInfo

SENSEL_API SenselStatus WINAPI senselGetFirmwareInfo(
    SENSEL_HANDLE handle,
    SenselFirmwareInfo *fw_info);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieve firmware device information

senselGetFrame

SENSEL_API SenselStatus WINAPI senselGetFrame(
    SENSEL_HANDLE handle,
    SenselFrameData *data);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Returns one frame of data in data.

senselGetFrameContent

SENSEL_API SenselStatus WINAPI senselGetFrameContent(
    SENSEL_HANDLE handle,
    unsigned char *content);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Get the current frame content mask from the device

senselGetLEDBrightness

SENSEL_API SenselStatus WINAPI senselGetLEDBrightness(
    SENSEL_HANDLE handle,
    unsigned char led_id,
    unsigned short *brightness);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieve the current brightness of an LED

senselGetMaxFrameRate

SENSEL_API SenselStatus WINAPI senselGetMaxFrameRate(
    SENSEL_HANDLE handle,
    unsigned short *val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Gets the maximum framerate at which the device should report

senselGetMaxLEDBrightness

SENSEL_API SenselStatus WINAPI senselGetMaxLEDBrightness(
    SENSEL_HANDLE handle,
    unsigned short *max_brightness);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieve the maximum brightness value an LED can be set to

senselGetNumAvailableFrames

SENSEL_API SenselStatus WINAPI senselGetNumAvailableFrames(
    SENSEL_HANDLE handle,
    unsigned int *num_avail_frames);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Returns in num_avail_frames the number of data frames available.

senselGetNumAvailableLEDs

SENSEL_API SenselStatus WINAPI senselGetNumAvailableLEDs(
    SENSEL_HANDLE handle,
    unsigned char *num_leds);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieve number of LEDs available on the device

senselGetPowerButtonPressed

SENSEL_API SenselStatus WINAPI senselGetPowerButtonPressed(
    SENSEL_HANDLE handle,
    unsigned char *pressed);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Pressed will be 1 if button was pressed or 0 otherwize

senselGetScanDetail

SENSEL_API SenselStatus WINAPI senselGetScanDetail(
    SENSEL_HANDLE handle,
    SenselScanDetail *detail);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Get the current scanning level setting

senselGetScanMode

SENSEL_API SenselStatus WINAPI senselGetScanMode(
    SENSEL_HANDLE handle,
    SenselScanMode *mode);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Gets the current scan mode.

senselGetSensorInfo

SENSEL_API SenselStatus WINAPI senselGetSensorInfo(
    SENSEL_HANDLE handle,
    SenselSensorInfo *info);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieves the sensor information

senselGetSupportedFrameContent

SENSEL_API SenselStatus WINAPI senselGetSupportedFrameContent(
    SENSEL_HANDLE handle,
    unsigned char *content);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Retrieve the frame content that the device supports

senselOpen

SENSEL_API SenselStatus WINAPI senselOpen(
    SENSEL_HANDLE *handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Opens the first available Sensel sensor

senselOpenDeviceByComPort

SENSEL_API SenselStatus WINAPI senselOpenDeviceByComPort(
    SENSEL_HANDLE *handle,
    unsigned char *com_port);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Opens the devices associated to the given com_port as returned by senselGetDeviceList. senselGetDeviceList must be called prior to this call

senselOpenDeviceByID

SENSEL_API SenselStatus WINAPI senselOpenDeviceByID(
    SENSEL_HANDLE *handle,
    unsigned char idx);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Opens the devices associated to the given idx as returned by senselGetDeviceList. senselGetDeviceList must be called prior to this call

senselOpenDeviceBySerialNum

SENSEL_API SenselStatus WINAPI senselOpenDeviceBySerialNum(
    SENSEL_HANDLE *handle,
    unsigned char *serial_num);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Opens the devices associated to the given serial_num as returned by senselGetDeviceList. senselGetDeviceList must be called prior to this call

senselReadReg

SENSEL_API SenselStatus WINAPI senselReadReg(
    SENSEL_HANDLE handle,
    unsigned char reg,
    unsigned char size,
    unsigned char *buf);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Reads size bytes from register reg and stores the value in buf.

senselReadRegVS

SENSEL_API SenselStatus WINAPI senselReadRegVS(
    SENSEL_HANDLE handle,
    unsigned char reg,
    unsigned int buf_size,
    unsigned char *buf,
    unsigned int *read_size);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Reads up to buf_size bytes from register reg and stores it in buf. On success, read_size will contain the number of bytes read from the register.

senselReadSensor

SENSEL_API SenselStatus WINAPI senselReadSensor(
    SENSEL_HANDLE handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Reads out and stores all pending frames from the sensor

senselSetBufferControl

SENSEL_API SenselStatus WINAPI senselSetBufferControl(
    SENSEL_HANDLE handle,
    unsigned char num);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the number of frame buffers the device should store internaly.

senselSetContactsEnableBlobMerge

SENSEL_API SenselStatus WINAPI senselSetContactsEnableBlobMerge(
    SENSEL_HANDLE handle,
    unsigned char val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Set contact blob merging setting

senselSetContactsMask

SENSEL_API SenselStatus WINAPI senselSetContactsMask(
    SENSEL_HANDLE handle,
    unsigned char mask);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the contact information reported by the sensor mask can be any combination of CONTACT_MASK_* Contacts returned in subsequent GetFrame calls will reflect this setting.

senselSetContactsMinForce

SENSEL_API SenselStatus WINAPI senselSetContactsMinForce(
    SENSEL_HANDLE handle,
    unsigned short val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the minimum force a contact needs to have to be reported

senselSetDynamicBaselineEnabled(SENSEL_HANDLE, unsigned char)

SENSEL_API SenselStatus WINAPI senselSetDynamicBaselineEnabled(
    SENSEL_HANDLE handle,
    unsigned char val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Enables or disables dynamic baselining based on val. If dynamic baseline is disabled, the baseline does not evolve over time.

senselSetFrameContent

SENSEL_API SenselStatus WINAPI senselSetFrameContent(
    SENSEL_HANDLE handle,
    unsigned char content);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the information returned by the sensor. content can be any combination of FRAME_CONTENT_*_MASK. FrameData returned in subsequent GetFrame calls will reflect this setting.

senselSetLEDBrightness

SENSEL_API SenselStatus WINAPI senselSetLEDBrightness(
    SENSEL_HANDLE handle,
    unsigned char led_id,
    unsigned short brightness);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Update the brightness of one LED

senselSetMaxFrameRate

SENSEL_API SenselStatus WINAPI senselSetMaxFrameRate(
    SENSEL_HANDLE handle,
    unsigned short val);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the maximum framerate at which the device should report

senselSetScanDetail

SENSEL_API SenselStatus WINAPI senselSetScanDetail(
    SENSEL_HANDLE handle,
    SenselScanDetail detail);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Set the level of scanning detail returned by the device. This setting trades precision for performance.

senselSetScanMode

SENSEL_API SenselStatus WINAPI senselSetScanMode(
    SENSEL_HANDLE handle,
    SenselScanMode mode);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Sets the current scan mode.

senselSoftReset

SENSEL_API SenselStatus WINAPI senselSoftReset(
    SENSEL_HANDLE handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Executes a soft reset the device referenced by handle. All registers are reset to their initial state

senselStartScanning

SENSEL_API SenselStatus WINAPI senselStartScanning(
    SENSEL_HANDLE handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Start sensor scanning

senselStopScanning

SENSEL_API SenselStatus WINAPI senselStopScanning(
    SENSEL_HANDLE handle);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Stop sensor scanning

senselWriteReg

SENSEL_API SenselStatus WINAPI senselWriteReg(
    SENSEL_HANDLE handle,
    unsigned char reg,
    unsigned char size,
    unsigned char *buf);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Writes size bytes from buf into register reg

senselWriteRegVS

SENSEL_API SenselStatus WINAPI senselWriteRegVS(
    SENSEL_HANDLE handle,
    unsigned char reg,
    unsigned int size,
    unsigned char *buf,
    unsigned int *write_size);  

Parameters

Return Value

SENSEL_OK on success or error

Discussion

Write up to size bytes from buf to register reg. On success, write_size will contain the number of bytes written to the register.

Typedefs

SENSEL_HANDLE

SenselAccelData

SenselContact

SenselContactState

SenselDeviceID

SenselDeviceList

SenselFirmwareInfo

SenselFrameData

SenselScanDetail

SenselScanMode

SenselSensorInfo

SenselStatus

SENSEL_HANDLE

typedef void *SENSEL_HANDLE;  

Discussion

Handle to a Sensel device

SenselAccelData

typedef struct {
    int x; // X axis acceleration
    int y; // Y axis acceleration
    int z; // Z axis acceleration
} SenselAccelData;  

Discussion

Accelerometer information

SenselContact

typedef struct {
    unsigned char content_bit_mask; // Mask of what contact data is valid
    unsigned char id; // Contact id
    unsigned int state; // Contact state (enum SenselContactState)
    float x_pos; // X position in mm
    float y_pos; // Y position in mm
    float total_force; // Total contact force in grams
    float area; // Area in sensor elements
    // CONTACT_MASK_ELLIPSE
    float orientation; // Angle in degrees
    float major_axis; // Length of the major axis in mm
    float minor_axis; // Length of the minor axis in mm
    // CONTACT_MASK_DELTAS
    float delta_x; // X contact displacement in mm
    float delta_y; // Y contact displacement in mm
    float delta_force; // Force delta in grams
    float delta_area; // Area delta in sensor elements
    // CONTACT_MASK_BOUNDING_BOX
    float min_x; // Bounding box min X coordinate in mm
    float min_y; // Bounding box min Y coordinate in mm
    float max_x; // Bounding box max X coordinate in mm
    float max_y; // Bounding box max Y coordinate in mm
    // CONTACT_MASK_PEAK
    float peak_x; // X position of the peak in mm
    float peak_y; // Y position of the peak in mm
    float peak_force; // Peak force in grams
} SenselContact;  

Discussion

Structure containing all information related to a detected contact The content_bit_mask reflects which data is valid

SenselContactState

typedef enum {
    CONTACT_INVALID = 0, // Contact is invalid
    CONTACT_START = 1, // Contact has started
    CONTACT_MOVE = 2, // Contact has moved
    CONTACT_END = 3, // Contact has ended
} SenselContactState;  

Discussion

Describes the current state of a contact

SenselDeviceID

typedef struct {
    unsigned char idx; // ID of the sensor
    unsigned char serial_num[64]; // Serial number of the sensor
    unsigned char com_port[64]; // Com port associated with the sensor
} SenselDeviceID;  

Discussion

Sensel identifier information

SenselDeviceList

typedef struct {
    unsigned char num_devices; // Num of devices found
    SenselDeviceID devices[SENSEL_MAX_DEVICES]; // Sensel device ID details
} SenselDeviceList;  

Discussion

List of connected Sensel devices

SenselFirmwareInfo

typedef struct {
    unsigned char fw_protocol_version; // Sensel communication protocol supported by the device
    unsigned char fw_version_major; // Major version of the firmware
    unsigned char fw_version_minor; // Minor version of the firmware
    unsigned short fw_version_build; // ??
    unsigned char fw_version_release; // ??
    unsigned short device_id; // Sensel device type
    unsigned char device_revision; // Device revision
} SenselFirmwareInfo;  

Discussion

Structure containing firmware information

SenselFrameData

typedef struct {
    unsigned char content_bit_mask; // Data contents of the frame
    int lost_frame_count; // Number of frames dropped
    unsigned char n_contacts; // Number of contacts
    SenselContact *contacts; // Array of contacts
    float *force_array; // Force image buffer
    unsigned char *labels_array; // Labels buffer
    SenselAccelData *accel_data; // Accelerometer data
} SenselFrameData;  

Discussion

Container for one frame of data. Available content of the frame needs to be checked by looking at the content_bit_mask

SenselScanDetail

typedef enum {
    SCAN_DETAIL_HIGH = 0, // Scan at full resolution
    SCAN_DETAIL_MEDIUM = 1, // Scan at half resolution
    SCAN_DETAIL_LOW = 2, // Scan at quarter resolution
    SCAN_DETAIL_UNKNOWN = 3,
} SenselScanDetail;  

Discussion

Describes the current state of a contact

SenselScanMode

typedef enum {
    SCAN_MODE_DISABLE,
    SCAN_MODE_SYNC,
    SCAN_MODE_ASYNC,
} SenselScanMode;  

Discussion

Device scan reporting mode

SenselSensorInfo

typedef struct {
    unsigned char max_contacts; // Maximum number of contacts the sensor supports
    unsigned short num_rows; // Total number of rows
    unsigned short num_cols; // Total number of columns
    float width; // Width of the sensor in millimeters
    float height; // Height of the sensor in millimeters
} SenselSensorInfo;  

Discussion

Structure containing sensor information

SenselStatus

typedef enum {
    SENSEL_OK = 0, // Call was successful
    SENSEL_ERROR = -1, // Call returned an error
} SenselStatus;  

Discussion

Status returned by API calls