{"_id":"5abba5c00117970012ba9b75","category":{"_id":"5abba5c00117970012ba9b71","version":"5abba5c00117970012ba9b6e","project":"55093b151c38c50d00611894","__v":0,"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","version":{"_id":"5abba5c00117970012ba9b6e","project":"55093b151c38c50d00611894","__v":2,"createdAt":"2018-03-28T14:25:04.622Z","releaseDate":"2018-03-28T14:25:04.622Z","categories":["5abba5c00117970012ba9b6f","5abba5c00117970012ba9b70","5abba5c00117970012ba9b71","5abba5c00117970012ba9b72","5ace17b040606a0003eabc75"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-03-18T09:06:50.664Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"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.\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, 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 USB or Bluetooth mode.\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 like the Slate name, the Slate size  or the 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 a 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 of the pen tip.\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 like below :\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.\nThis 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 Top dot button of the Slate is pressed (called Button1).\n - the Top dot button of the Slate is long pressed .\n - the Top button of the Slate is pressed (called Button 2).\n - the Top button of the Slate is long pressed.\n - the battery is in charge or not.\n - a SD card is removed from the Slate.\n - the Slate refresh is done.\n \n#### EventStatus\nThis event is sent when:\n - the battery level has changed (battery level is given in percentage).\n - the battery status has changed (battery is in charge or not).\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 the ISKN Pen 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 pen tip in hundredth degrees (float precision). Two angles are used:\n    + Rx: the angle between the pen tip axis and the z axis (from 0° to 180°).\n    + Ry: the angle between the projection of the pen tip axis on the xy plane, and the x axis (from -180° to 180°).\n\n#### EventPen3D\nThis event is sent when the ISKN Pen 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 pen tip axis and the z axis (from 0° to 180°).\n    + Ry: the angle between the projection of the pen tip axis on the xy plane, and the x axis (from -180° to 180°).\n\n#### EventLocQuality\nThe Slate has 32 magnetic sensors included which track the exact position and the angle of inclination of the ISKN Ring (the magnet).\nOther magnetic items can disturb this connection and cause accuracy problems while drawing on the Slate.\nThis items could be an iPad or a PC (which have to be at least 20 cm | 8 inches away when used along with the Slate), smartphones, speakers, other iskn Rings etc.\n\nThe EventLocQuality is a magnetic indicator that allows the developer to detect  the magnetic disturbance via three methods :\n - **getLocStatus** method which indicates the pen localisation status.\n - **getDisturbanceLevel** method which indicates the maximum disturbance value reached ( this value is between 0 and 255 per sensor).\n - **getInnovation** method which returns an array of 32 indicators of perturbation per sensor (those values are between 0 and 255 ).\n\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\n### Information Classes\n\n#### Device\nThis class contains the device information like Slate name, firmware version, the width, the height... \nThose information are updated when the application requests a Slate description.It also allows to change some Slate settings via the methods below :\n- **setDeviceName** method which sets a new Slate name.\n- **setLocQualityParameters** method which sets the sending frequency of  the event **EventLocQuality** on idle state (No pen detected on the Slate surface) and also on localisation state (A pen is localised on the Slate surface). \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. ## 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, 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 USB or Bluetooth mode. 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 like the Slate name, the Slate size or the 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. 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 like below : ### 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. This 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 Top dot button of the Slate is pressed (called Button1). - the Top dot button of the Slate is long pressed . - the Top button of the Slate is pressed (called Button 2). - the Top button of the Slate is long pressed. - the battery is in charge or not. - a SD card is removed from the Slate. - the Slate refresh is done. #### EventStatus This event is sent when: - the battery level has changed (battery level is given in percentage). - the battery status has changed (battery is in charge or not). #### 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 the ISKN Pen 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 pen tip in hundredth degrees (float precision). Two angles are used: + Rx: the angle between the pen tip axis and the z axis (from 0° to 180°). + Ry: the angle between the projection of the pen tip axis on the xy plane, and the x axis (from -180° to 180°). #### EventPen3D This event is sent when the ISKN Pen 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 pen tip axis and the z axis (from 0° to 180°). + Ry: the angle between the projection of the pen tip axis on the xy plane, and the x axis (from -180° to 180°). #### EventLocQuality The Slate has 32 magnetic sensors included which track the exact position and the angle of inclination of the ISKN Ring (the magnet). Other magnetic items can disturb this connection and cause accuracy problems while drawing on the Slate. This items could be an iPad or a PC (which have to be at least 20 cm | 8 inches away when used along with the Slate), smartphones, speakers, other iskn Rings etc. The EventLocQuality is a magnetic indicator that allows the developer to detect the magnetic disturbance via three methods : - **getLocStatus** method which indicates the pen localisation status. - **getDisturbanceLevel** method which indicates the maximum disturbance value reached ( this value is between 0 and 255 per sensor). - **getInnovation** method which returns an array of 32 indicators of perturbation per sensor (those values are between 0 and 255 ). ### 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 like Slate name, firmware version, the width, the height... Those information are updated when the application requests a Slate description.It also allows to change some Slate settings via the methods below : - **setDeviceName** method which sets a new Slate name. - **setLocQualityParameters** method which sets the sending frequency of the event **EventLocQuality** on idle state (No pen detected on the Slate surface) and also on localisation state (A pen is localised on the Slate surface). #### 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).