{"_id":"5509402a2ee8bf2b0049191c","version":{"_id":"55093b161c38c50d00611897","project":"55093b151c38c50d00611894","__v":4,"createdAt":"2015-03-18T08:45:10.369Z","releaseDate":"2015-03-18T08:45:10.368Z","categories":["55093b161c38c50d00611898","55093ee2961f17170070abb9","55093ee9961f17170070abba","55093ef52ee8bf2b00491916"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"__v":4,"category":{"_id":"55093ee9961f17170070abba","project":"55093b151c38c50d00611894","version":"55093b161c38c50d00611897","__v":1,"pages":["5509402a2ee8bf2b0049191c"],"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-18T09:01:29.410Z","from_sync":false,"order":2,"slug":"api-presentation","title":"API Presentation"},"user":"55093a63a4ae180d00c0eaf5","project":"55093b151c38c50d00611894","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-03-18T09:06:50.664Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"## Introduction\n\nThis page presents the ISKN API, its basic components and the way it should be used to develop an application using the ISKN Slate hardware.\n\n## The API\n\nThe ISKN API is the official library provided by the ISKN team to enable applications development using the ISKN hardware. \nIt provides an interface to communicate with the Slate, request services and listen to its events.\n\nIn order to use the API, the application should include the API header files and link with its shared library.\n\nWhen a Slate is turned on in Live mode, it waits for a connection from the USB or Bluetooth device. \nThe API provides a method that allows the application to connect to the Slate on one of the two interfaces (USB/Bluetooth).\n\nOnce connected, the Slate waits for application requests.\nThe requests are split into two kinds :\n\n### Single block requests\nThe Slate replies to those requests instantaneously by sending the requested information. \nFor example, the application may request device information (its name, the size of the capture area...),\nSD Card status or battery status.\n\n### Event subscription requests\nThe application can subscribe to one or more Slate events. \nThere are many events that can be generated by the Slate, such as a pen recognition event, that occurs when \na pen (or an object containing a certified ISKN magnet) enters the Slate view field. \nThe pen loss event occurs when the pen (or the object) is out of the view field.\nWhen a pen moves, the Slate generates events depending on the application request such as the position, orientation and contact \nof the pen tip in 2D and 3D.\n\nWhen an event happens, the Slate sends a data-block describing the event to the Host through the API interface. \nThe API invokes a method of a listener class and forwards the event as an argument to the application.\nTherefore, the application should implement the listener interface (abstract class in C++) in order to receive the events. \n\n## The components\nThe API contains several components presented as classes.\nClasses may be split in groups :\n\n### Main Classes\nMain Classes are the classes that give direct access to the Slate :\n\n#### SlateManager\nThis class is the main class. It offers methods to communicate with the Slate (connect, request, subscribe ...) and it registers the Listener class.\n\n### Interface Class\nThe API has a single Interface Class:\n\n#### Listener\nThis class is an interface that should be implemented by the application in order to receive the Slate events.\nThe implementing class should be registered by the SlateManager using the `registerListener` method.\n\nIt must implement two methods `connexionStatusChanged` and `ProcessEvent`.\nThe `connexionStatusChanged` method is called whenever the connection status has changed.\nThe `ProcessEvent` is called when an event is received from the Slate.\n\n### Event Classes\nSome classes are used to hold event parameters.\nThese events are sent by the Slate when a subscription request has been made.\n\n#### EventDescription\nThis event is sent by the Slate when a device description is requested.\n\n#### EventSoftware\nThis event is sent:\n - when a recognized magnetic object enters the Slate view field.\n - when a recognized magnetic object leaves the Slate view field.\n - every second as a handshake event.\n \n#### EventHardware\nThis event is sent when:\n - the button 1 of the Slate is pressed.\n - the button 2 of the Slate is pressed.\n - a SD card is inserted into the Slate.\n - a SD card is removed from the Slate.\n \n#### EventStatus\nThis event is sent when:\n - the battery level has changed (battery level is given in percentage).\n - the SD card is plugged in or out.\n\n#### EventObject3D\nThis event is sent when a known magnetic object is within the Slate view field.\nIt provides:\n - the magnet position in millimeters (float precision).\n - the rotation angles of the magnet in hundredth of degrees(float precision). Two angles are used:\n    + Rx: the angle between the magnet axis and the z axis (from 0° to 180°).\n    + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°).\n\n#### EventPen2D\nThis event is sent when a known magnetic object is within the Slate view field.\nIt provides:\n - the pen tip position (x and y axis) of the pen in millimeters (float precision).\n - the rotation angles of the magnet in hundredth degrees (float precision). Two angles are used:\n    + Rx: the angle between the magnet axis and the z axis (from 0° to 180°).\n    + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°).\n\n#### EventPen3D\nThis event is sent when a known magnetic object is within the Slate view field.\nIt provides:\n - the pen tip position(x,y and z axis) in millimeters (float precision).\n - the rotation angles of the pen tip in hundredth degrees (float precision). Two angles are used:\n    + Rx: the angle between the magnet axis and the z axis (from 0° to 180°).\n    + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°).\n\n#### EventAccelerometer\nThis event provides the Slate acceleration value on each axis (x,y and z) given in milli-g.\n\n### Data Classes\n\n#### Vector3D\nThis class holds a 3D information (x,y,z). The coordinates are given in float.\n\n#### Vector2D\nThis class holds a 2D information (x,y). The coordinates are given in float.\n\n#### Rect\nThis class holds a rectangle coordinates (left, top, width, height). \nThe coordinates are given in float.\n\n#### Size\nThis class holds a rectangle size (width, height). \nThe coordinates are given in float.\n\n#### isknDate\nThis class holds date information (Year, Month, Day, DayOfWeek). \nThe date parameters are given in unsigned short int.\n\n#### isknTime\nThis class holds time information (Hour, Minute, Second). \nThe time parameters are given in unsigned short int.\n\n### Information Classes\n\n#### Device\nThis class contains the device information. It is updated when the application requests a Slate description.\n\n#### Error\nThis class contains the error messages that may be generated by the API. \nThe messages are available in two languages (English EN_US and French FR_FR).\n\n#### LanguageId\nThis class defines the language used by the API. \nIn this version, only two languages are supported (English EN_US and French FR_FR).","excerpt":"","slug":"iskn-api-presentation","type":"basic","title":"ISKN API Presentation"}

ISKN API Presentation


## Introduction This page presents the ISKN API, its basic components and the way it should be used to develop an application using the ISKN Slate hardware. ## The API The ISKN API is the official library provided by the ISKN team to enable applications development using the ISKN hardware. It provides an interface to communicate with the Slate, request services and listen to its events. In order to use the API, the application should include the API header files and link with its shared library. When a Slate is turned on in Live mode, it waits for a connection from the USB or Bluetooth device. The API provides a method that allows the application to connect to the Slate on one of the two interfaces (USB/Bluetooth). Once connected, the Slate waits for application requests. The requests are split into two kinds : ### Single block requests The Slate replies to those requests instantaneously by sending the requested information. For example, the application may request device information (its name, the size of the capture area...), SD Card status or battery status. ### Event subscription requests The application can subscribe to one or more Slate events. There are many events that can be generated by the Slate, such as a pen recognition event, that occurs when a pen (or an object containing a certified ISKN magnet) enters the Slate view field. The pen loss event occurs when the pen (or the object) is out of the view field. When a pen moves, the Slate generates events depending on the application request such as the position, orientation and contact of the pen tip in 2D and 3D. When an event happens, the Slate sends a data-block describing the event to the Host through the API interface. The API invokes a method of a listener class and forwards the event as an argument to the application. Therefore, the application should implement the listener interface (abstract class in C++) in order to receive the events. ## The components The API contains several components presented as classes. Classes may be split in groups : ### Main Classes Main Classes are the classes that give direct access to the Slate : #### SlateManager This class is the main class. It offers methods to communicate with the Slate (connect, request, subscribe ...) and it registers the Listener class. ### Interface Class The API has a single Interface Class: #### Listener This class is an interface that should be implemented by the application in order to receive the Slate events. The implementing class should be registered by the SlateManager using the `registerListener` method. It must implement two methods `connexionStatusChanged` and `ProcessEvent`. The `connexionStatusChanged` method is called whenever the connection status has changed. The `ProcessEvent` is called when an event is received from the Slate. ### Event Classes Some classes are used to hold event parameters. These events are sent by the Slate when a subscription request has been made. #### EventDescription This event is sent by the Slate when a device description is requested. #### EventSoftware This event is sent: - when a recognized magnetic object enters the Slate view field. - when a recognized magnetic object leaves the Slate view field. - every second as a handshake event. #### EventHardware This event is sent when: - the button 1 of the Slate is pressed. - the button 2 of the Slate is pressed. - a SD card is inserted into the Slate. - a SD card is removed from the Slate. #### EventStatus This event is sent when: - the battery level has changed (battery level is given in percentage). - the SD card is plugged in or out. #### EventObject3D This event is sent when a known magnetic object is within the Slate view field. It provides: - the magnet position in millimeters (float precision). - the rotation angles of the magnet in hundredth of degrees(float precision). Two angles are used: + Rx: the angle between the magnet axis and the z axis (from 0° to 180°). + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°). #### EventPen2D This event is sent when a known magnetic object is within the Slate view field. It provides: - the pen tip position (x and y axis) of the pen in millimeters (float precision). - the rotation angles of the magnet in hundredth degrees (float precision). Two angles are used: + Rx: the angle between the magnet axis and the z axis (from 0° to 180°). + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°). #### EventPen3D This event is sent when a known magnetic object is within the Slate view field. It provides: - the pen tip position(x,y and z axis) in millimeters (float precision). - the rotation angles of the pen tip in hundredth degrees (float precision). Two angles are used: + Rx: the angle between the magnet axis and the z axis (from 0° to 180°). + Ry: the angle between the projection of the manget axis on the xy plane, and the x axis (from -180° to 180°). #### EventAccelerometer This event provides the Slate acceleration value on each axis (x,y and z) given in milli-g. ### Data Classes #### Vector3D This class holds a 3D information (x,y,z). The coordinates are given in float. #### Vector2D This class holds a 2D information (x,y). The coordinates are given in float. #### Rect This class holds a rectangle coordinates (left, top, width, height). The coordinates are given in float. #### Size This class holds a rectangle size (width, height). The coordinates are given in float. #### isknDate This class holds date information (Year, Month, Day, DayOfWeek). The date parameters are given in unsigned short int. #### isknTime This class holds time information (Hour, Minute, Second). The time parameters are given in unsigned short int. ### Information Classes #### Device This class contains the device information. It is updated when the application requests a Slate description. #### Error This class contains the error messages that may be generated by the API. The messages are available in two languages (English EN_US and French FR_FR). #### LanguageId This class defines the language used by the API. In this version, only two languages are supported (English EN_US and French FR_FR).