Skip to content
Permalink
master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
 
 
Cannot retrieve contributors at this time
/******************************************************************************************
* MIT License
*
* Copyright (c) 2013-2017 Sensel, Inc.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
******************************************************************************************/
#ifndef __SENSEL_H__
#define __SENSEL_H__
#ifdef WIN32
#include <windows.h>
#else
#define WINAPI
#endif
#ifdef SENSEL_EXPORTS
#define SENSEL_API __declspec(dllexport)
#else
#define SENSEL_API __declspec(dllimport)
#endif
#ifndef WIN32
#ifdef SENSEL_API
#undef SENSEL_API
#define SENSEL_API __attribute__ ((visibility ("default")))
#endif
#endif
#define SENSEL_MAX_DEVICES 16 // Maximum number of devices supported by the API
#define FRAME_CONTENT_PRESSURE_MASK 0x01 // Mask indicating that the frame includes pressure data
#define FRAME_CONTENT_LABELS_MASK 0x02 // Mask indicating that the frame includes labels data
#define FRAME_CONTENT_CONTACTS_MASK 0x04 // Mask indicating that the frame includes contacts data
#define FRAME_CONTENT_ACCEL_MASK 0x08 // Mask indicating that the frame includes acceleromter data
#define CONTACT_MASK_ELLIPSE 0x01 // Mask indicating that the contact data contains ellipse info
#define CONTACT_MASK_DELTAS 0x02 // Mask indicating that the contact data contains deltas info
#define CONTACT_MASK_BOUNDING_BOX 0x04 // Mask indicating that the contact data contains bound box info
#define CONTACT_MASK_PEAK 0x08 // Mask indicating that the contact data contains peak info
#ifdef __cplusplus
extern "C" {
#endif
/*!
* @discussion Handle to a Sensel device
*/
typedef void *SENSEL_HANDLE;
/*!
* @discussion Status returned by API calls
*/
typedef enum
{
SENSEL_OK = 0, // Call was successful
SENSEL_ERROR = -1, // Call returned an error
} SenselStatus;
/*!
* @discussion Device scan reporting mode
*/
typedef enum
{
SCAN_MODE_DISABLE,
SCAN_MODE_SYNC,
SCAN_MODE_ASYNC,
} SenselScanMode;
/*!
* @discussion Describes the current state of a contact
*/
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
*/
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 Structure containing sensor information
*/
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 firmware information
*/
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 all information related to a detected contact
* The content_bit_mask reflects which data is valid
*/
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 Accelerometer information
*/
typedef struct
{
int x; // X axis acceleration
int y; // Y axis acceleration
int z; // Z axis acceleration
} SenselAccelData;
/*!
* @discussion Container for one frame of data.
* Available content of the frame needs to be checked by looking at the content_bit_mask
*/
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 Sensel identifier information
*/
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 List of connected Sensel devices
*/
typedef struct
{
unsigned char num_devices; // Num of devices found
SenselDeviceID devices[SENSEL_MAX_DEVICES]; // Sensel device ID details
} SenselDeviceList;
/*!
* @param handle Sensel device handle to be allocated
* @return SENSEL_OK on success or error
* @discussion Opens the first available Sensel sensor
*/
SENSEL_API
SenselStatus WINAPI senselOpen(SENSEL_HANDLE *handle);
/*!
* @param list Device list to be populated
* @return SENSEL_OK on success or error
* @discussion Scans for all availale sensel devices and populates list accordingly
*/
SENSEL_API
SenselStatus WINAPI senselGetDeviceList(SenselDeviceList *list);
/*!
* @param handle Sensel device handle to be initialized
* @param idx identifier of the device to open
* @return 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
*/
SENSEL_API
SenselStatus WINAPI senselOpenDeviceByID(SENSEL_HANDLE *handle, unsigned char idx);
/*!
* @param handle Sensel device handle to be initialized
* @param serial_num serial_number of the device to open
* @return 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
*/
SENSEL_API
SenselStatus WINAPI senselOpenDeviceBySerialNum(SENSEL_HANDLE *handle, unsigned char *serial_num);
/*!
* @param handle Sensel device handle to be initialized
* @param com_port com_port path of the device to open
* @return 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
*/
SENSEL_API
SenselStatus WINAPI senselOpenDeviceByComPort(SENSEL_HANDLE *handle, unsigned char *com_port);
/*!
* @param handle Sensel device to be closed
* @return SENSEL_OK on success or error
* @discussion Closes the device associated with handle and frees all memory.
*/
SENSEL_API
SenselStatus WINAPI senselClose(SENSEL_HANDLE handle);
/*!
* @param handle Sensel device to reset
* @return SENSEL_OK on success or error
* @discussion Executes a soft reset the device referenced by handle.
* All registers are reset to their initial state
*/
SENSEL_API
SenselStatus WINAPI senselSoftReset(SENSEL_HANDLE handle);
/*!
* @param handle Sensel device handle to information about
* @param info Pointer to a structure to populate
* @return SENSEL_OK on success or error
* @discussion Retrieves the sensor information
*/
SENSEL_API
SenselStatus WINAPI senselGetSensorInfo(SENSEL_HANDLE handle, SenselSensorInfo *info);
/*!
* @param handle Sensel device handle for which to create a FrameData structure for
* @param data Pointer to FrameData to allocate.
* @return SENSEL_OK on success or error
* @discussion Allocates a FrameData and initializes all buffers according to device capabilities.
*/
SENSEL_API
SenselStatus WINAPI senselAllocateFrameData(SENSEL_HANDLE handle, SenselFrameData **data);
/*!
* @param handle Sensel device handle
* @param data FrameData to free.
* @return SENSEL_OK on success or error
* @discussion Frees all memory allocated to FrameData including the FrameData itself.
*/
SENSEL_API
SenselStatus WINAPI senselFreeFrameData(SENSEL_HANDLE handle, SenselFrameData *data);
/*!
* @param handle Sensel device handle
* @param detail Scan detail level
* @return SENSEL_OK on success or error
* @discussion Set the level of scanning detail returned by the device. This setting trades precision for performance.
*/
SENSEL_API
SenselStatus WINAPI senselSetScanDetail(SENSEL_HANDLE handle, SenselScanDetail detail);
/*!
* @param handle Sensel device handle
* @param detail Pointer to scan detail level to retrieve
* @return SENSEL_OK on success or error
* @discussion Get the current scanning level setting
*/
SENSEL_API
SenselStatus WINAPI senselGetScanDetail(SENSEL_HANDLE handle, SenselScanDetail *detail);
/*!
* @param handle Sensel device handle
* @param content Pointer to frame content supported by device
* @return SENSEL_OK on success or error
* @discussion Retrieve the frame content that the device supports
*/
SENSEL_API
SenselStatus WINAPI senselGetSupportedFrameContent(SENSEL_HANDLE handle, unsigned char *content);
/*!
* @param handle Sensel device handle
* @param content Frame content mask
* @return 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.
*/
SENSEL_API
SenselStatus WINAPI senselSetFrameContent(SENSEL_HANDLE handle, unsigned char content);
/*!
* @param handle Sensel device handle
* @param content Pointer to content level to retrieve
* @return SENSEL_OK on success or error
* @discussion Get the current frame content mask from the device
*/
SENSEL_API
SenselStatus WINAPI senselGetFrameContent(SENSEL_HANDLE handle, unsigned char *content);
/*!
* @param handle Sensel device handle
* @return SENSEL_OK on success or error
* @discussion Start sensor scanning
*/
SENSEL_API
SenselStatus WINAPI senselStartScanning(SENSEL_HANDLE handle);
/*!
* @param handle Sensel device handle
* @return SENSEL_OK on success or error
* @discussion Stop sensor scanning
*/
SENSEL_API
SenselStatus WINAPI senselStopScanning(SENSEL_HANDLE handle);
/*!
* @param handle Sensel device handle
* @return SENSEL_OK on success or error
* @discussion Reads out and stores all pending frames from the sensor
*/
SENSEL_API
SenselStatus WINAPI senselReadSensor(SENSEL_HANDLE handle);
/*!
* @param handle Sensel device handle
* @param num_avail_frames Will contain the number of frames available to GetFrame
* @return SENSEL_OK on success or error
* @discussion Returns in num_avail_frames the number of data frames available.
*/
SENSEL_API
SenselStatus WINAPI senselGetNumAvailableFrames(SENSEL_HANDLE handle, unsigned int *num_avail_frames);
/*!
* @param handle Sensel device handle
* @param data Pointer to pre-allocated FrameData to populate
* @return SENSEL_OK on success or error
* @discussion Returns one frame of data in data.
*/
SENSEL_API
SenselStatus WINAPI senselGetFrame(SENSEL_HANDLE handle, SenselFrameData *data);
/*!
* @param handle Sensel device handle
* @param num_leds Pointer to number of leds on device
* @return SENSEL_OK on success or error
* @discussion Retrieve number of LEDs available on the device
*/
SENSEL_API
SenselStatus WINAPI senselGetNumAvailableLEDs(SENSEL_HANDLE handle, unsigned char *num_leds);
/*!
* @param handle Sensel device handle
* @param max_brightness Pointer to maximum per LED brightness
* @return SENSEL_OK on success or error
* @discussion Retrieve the maximum brightness value an LED can be set to
*/
SENSEL_API
SenselStatus WINAPI senselGetMaxLEDBrightness(SENSEL_HANDLE handle, unsigned short *max_brightness);
/*!
* @param handle Sensel device handle
* @param led_id Index of the LED to update
* @param brightness Brightness setting
* @return SENSEL_OK on success or error
* @discussion Update the brightness of one LED
*/
SENSEL_API
SenselStatus WINAPI senselSetLEDBrightness(SENSEL_HANDLE handle, unsigned char led_id, unsigned short brightness);
/*!
* @param handle Sensel device handle
* @param led_id Index of the LED to update
* @param brightness Pointer to brightness setting
* @return SENSEL_OK on success or error
* @discussion Retrieve the current brightness of an LED
*/
SENSEL_API
SenselStatus WINAPI senselGetLEDBrightness(SENSEL_HANDLE handle, unsigned char led_id, unsigned short *brightness);
/*!
* @param handle Sensel device handle
* @param pressed Pointer to hold state of power button
* @return SENSEL_OK on success or error
* @discussion Pressed will be 1 if button was pressed or 0 otherwize
*/
SENSEL_API
SenselStatus WINAPI senselGetPowerButtonPressed(SENSEL_HANDLE handle, unsigned char *pressed);
/*
* Advanced API
* The following calls are advanced and can break functionality if not used properly.
*/
/*!
* @param handle Sensel device handle
* @param fw_info Pointer to SenselFirmwareInfo structure to populate
* @return SENSEL_OK on success or error
* @discussion Retrieve firmware device information
*/
SENSEL_API
SenselStatus WINAPI senselGetFirmwareInfo(SENSEL_HANDLE handle, SenselFirmwareInfo* fw_info);
/*!
* @param handle Sensel device handle
* @param val 0 to disable - 1 to enable
* @return SENSEL_OK on success or error
* @discussion Set contact blob merging setting
*/
SENSEL_API
SenselStatus WINAPI senselSetContactsEnableBlobMerge(SENSEL_HANDLE handle, unsigned char val);
/*!
* @param handle Sensel device handle
* @param val Pointer to contain current setting
* @return SENSEL_OK on success or error
* @discussion Get contact blob merging setting
*/
SENSEL_API
SenselStatus WINAPI senselGetContactsEnableBlobMerge(SENSEL_HANDLE handle, unsigned char *val);
/*!
* @param handle Sensel device handle
* @param val Force value
* @return SENSEL_OK on success or error
* @discussion Sets the minimum force a contact needs to have to be reported
*/
SENSEL_API
SenselStatus WINAPI senselSetContactsMinForce(SENSEL_HANDLE handle, unsigned short val);
/*!
* @param handle Sensel device handle
* @param val Pointer to contain current setting
* @return SENSEL_OK on success or error
* @discussion Gets the minimum force a contact needs to have to be reported
*/
SENSEL_API
SenselStatus WINAPI senselGetContactsMinForce(SENSEL_HANDLE handle, unsigned short *val);
/*!
* @param handle Sensel device handle
* @param val true: Enabled - false: Disabled
* @return SENSEL_OK on success or error
* @discussion Sets if the baseline is dynamic and evolves over time
*/
SENSEL_API
SenselStatus WINAPI senselSetDynamicBaselineEnabled(SENSEL_HANDLE handle, unsigned char val);
/*!
* @param handle Sensel device handle
* @param val Pointer to contain current setting
* @return SENSEL_OK on success or error
* @discussion Retreives the current dynamic baselining setting
*/
SENSEL_API
SenselStatus WINAPI senselGetDynamicBaselineEnabled(SENSEL_HANDLE handle, unsigned char *val);
/*!
* @param handle Sensel device handle
* @param num Number of buffers
* @return SENSEL_OK on success or error
* @discussion Sets the number of frame buffers the device should store internaly.
*/
SENSEL_API
SenselStatus WINAPI senselSetBufferControl(SENSEL_HANDLE handle, unsigned char num);
/*!
* @param handle Sensel device handle
* @param num Pointer to contain current setting
* @return SENSEL_OK on success or error
* @discussion Gets the number of frame buffers the device should store internaly.
*/
SENSEL_API
SenselStatus WINAPI senselGetBufferControl(SENSEL_HANDLE handle, unsigned char *num);
/*!
* @param handle Sensel device handle
* @param mode Scan mode setting
* @return SENSEL_OK on success or error
* @discussion Sets the current scan mode.
*/
SENSEL_API
SenselStatus WINAPI senselSetScanMode(SENSEL_HANDLE handle, SenselScanMode mode);
/*!
* @param handle Sensel device handle
* @param mode Pointer to retrieve Scan mode setting
* @return SENSEL_OK on success or error
* @discussion Gets the current scan mode.
*/
SENSEL_API
SenselStatus WINAPI senselGetScanMode(SENSEL_HANDLE handle, SenselScanMode *mode);
/*!
* @param handle Sensel device handle
* @param val Max framerate
* @return SENSEL_OK on success or error
* @discussion Sets the maximum framerate at which the device should report
*/
SENSEL_API
SenselStatus WINAPI senselSetMaxFrameRate(SENSEL_HANDLE handle, unsigned short val);
/*!
* @param handle Sensel device handle
* @param val Pointer to retrieve current max framerate
* @return SENSEL_OK on success or error
* @discussion Gets the maximum framerate at which the device should report
*/
SENSEL_API
SenselStatus WINAPI senselGetMaxFrameRate(SENSEL_HANDLE handle, unsigned short *val);
/*!
* @param handle Sensel device handle
* @param mask Contact information mask
* @return 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.
*/
SENSEL_API
SenselStatus WINAPI senselSetContactsMask(SENSEL_HANDLE handle, unsigned char mask);
/*!
* @param handle Sensel device handle
* @param mask Pointer to retrieve current max framerate
* @return SENSEL_OK on success or error
* @discussion Gets the current contact mask setting for the device
*/
SENSEL_API
SenselStatus WINAPI senselGetContactsMask(SENSEL_HANDLE handle, unsigned char *mask);
/*!
* @param handle Sensel device handle
* @param reg Register to read
* @param size Size of the register
* @param buf Buffer to store the result
* @return SENSEL_OK on success or error
* @discussion Reads size bytes from register reg and stores the value in buf.
*/
SENSEL_API
SenselStatus WINAPI senselReadReg(SENSEL_HANDLE handle, unsigned char reg, unsigned char size, unsigned char *buf);
/*!
* @param handle Sensel device handle
* @param reg Register to write
* @param size Size of the register
* @param buf Buffer containing the data to write
* @return SENSEL_OK on success or error
* @discussion Writes size bytes from buf into register reg
*/
SENSEL_API
SenselStatus WINAPI senselWriteReg(SENSEL_HANDLE handle, unsigned char reg, unsigned char size, unsigned char *buf);
/*!
* @param handle Sensel device handle
* @param reg Register to write
* @param buf_size Size of the "buf" buffer
* @param buf Buffer to store the result
* @param read_size Variable to store the number of bytes read from register
* @return 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.
*/
SENSEL_API
SenselStatus WINAPI senselReadRegVS(SENSEL_HANDLE handle, unsigned char reg, unsigned int buf_size, unsigned char *buf, unsigned int *read_size);
/*!
* @param handle Sensel device handle
* @param reg Register to write
* @param size Size of data to write from buf
* @param buf Buffer holding data to write
* @param write_size Variable to store the number of bytes actually written
* @return 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.
*/
SENSEL_API
SenselStatus WINAPI senselWriteRegVS(SENSEL_HANDLE handle, unsigned char reg, unsigned int size, unsigned char *buf, unsigned int *write_size);
#ifdef __cplusplus
}
#endif
#endif //__SENSEL_H__