HOW-TO - Use the SDK demo

Step-by-step guide

Explore the content of the Atrium SDK demo application

1. Open the Atrium SDK demo software.

   You should find the executable of the Atrium SDK demo under "C:\Program Files (x86)\atrium-sdk\atrium-sdk.exe"
2. The application is divided in 3 main blocks
   
   1. The documentation of the different Atrium object types
   2. Some file examples to describe the exchanges required to program users and cards, access levels or camera modules.
   3. The complete Atrium SDK demo is divided in 3 different groups:
      1. Records: allowing read/write/add/delete of every object types of the Atrium system.
      2. Commands: allowing different types of actions such as door lock/unlock, set user location and much more.
      3. Events: allowing to retrieve the events saved on the Atrium devices.

Atrium SDK Documentation - Object types

1. From the drop-down menu, select SDK Documentation.
   
2. The documentations list all the Object Types supported in the Atrium SDK. Each of these object types may contain records, commands and related events. By default, the list shows only the basic Object types which are most commonly used. The list can be switch to Advanced display at any time with the Basic/Advanced button located in the top-right corner of the panel. 
   
3. From the list, click on a specific Object type to explore its content. At any time, click on the Close button to close the current view. 
4. According to its content, a list of available Records, Commands and Events will be displayed for this Object type. Other information are also available in this view such as the Object type XML tag name and the number of Object id supported for this Object type. i.e.: maximum 10000 users supported on the system.
   
5. Using the Object record or Command drop-downs, select an item to explore its content. 
6. The detailed view specifies the Record type or Command tag name along with the detailed content of the record or command to use. Again, the list can be switch to Advanced display at any time with the Basic/Advanced button located in the top-right corner of the panel. 
   
7. Click on the event button to visualize the list of events related to this object types.
   

Atrium SDK examples

1. 1. From the drop-down menu, select SDK Examples.
      
   2. This menu shows a list of available files which can be downloaded via their download link.
      
   3. Click on the View link of a specific file to visualized its content in the viewer at the bottom the page.
      
   4. The atrium_sdk.xsd file can be used to validate the framing of the XML data before sending it to the Atrium device target. This file also explains the structure of the data that can be exchanged with the Atrium device target.
   5. The list shows also examples of communications with the Atrium SDK. Some files, such as the SDK example - Add new user, contain back and forth communications with the Atrium SDK. All these exchanges have been put together within a single file to ease the reading. Each "real" communication to and from the Atrium SDK is always surrounded by the XML tag name <SDK>. The Atrium SDK answers always contain the result attribute "res".

Connect to the Atrium device target

1. Click on the drop-down menu and select SDK demo - Login
   
2. On the login page, type in the URL of your Atrium device target.
   
3. Then type in the username and password of the user that you wish to use for login. It could be any user, as long as it has the SDK access enabled like specified in the prerequisite section.
4. When ready, press the Login button to connect to the Atrium device target. At any time, select the SDK Demo - Logout option from the drop-down menu to disconnect the application from the Atrium device target. The Atrium device target will also close the session after 15 minutes of inactivity.
   

SDK Demo - Commands

1. The Command view is the default landing page after a login. Then, the first thing to do is to select an Object type to play with.
   
2. The Object type list is quite similar to the Documentation view. Here again, the list can be switch between Basic to Advanced display at any time using the Basic/Advanced button located in the top-right corner of the panel. 
   
3. The Command view is divided in 4 panels:
   1. The Object type controller is the main panel of the Command view. It works closely with the Detailed view. The Object type controller regroups several information such as:
      
      
      1. The Name of the selected Object type. The Object type name is an hyperlink to the Object type list and can be used to switch to another Object type.
      2. The Target serial number to which the data has to be send. If the Atrium target device is a master controller, it is possible to populate the list of the available targets (master and sub-controllers) by fetching all the Object id of the Object type IP client.
      3. If the selected Object type supports more than one occurrence (more than one Object id), the object id fields should be visible. The Object id field is '0' based meaning that it starts at 0 and can vary up to the maximum of object id minus 1. Some commands can use a range of Object id and apply to multiple object id while some other commands are restricted to use a single object id at a time. For instance, you could read a range of object id for user 0 to 9 but would only be able to write or add one user at a time. The Detailed view always displays the content of the Object Id start. The Object id Start and End are included in the specified range.
      4. The Send button is used to package and send the current command to the Atrium device target.
      5. The different types of Commands that can be selected for this Object types.
         1. If the Object type supports Record types, a list of Record command will be visible in the Command drop-down. Each commands interact with the current selected Record type (Configuration, Status, Trouble, Private, Status 2, Location...). All Object types support the same record commands:
            
            
            1. Record - Read: Requests to read the content selected record type and object id. The result data should be visible in the Detailed view. If no Detailed checkbox are selected, the command reads all available data. If at least one Detailed checkbox is selected, the read command request to read only the specified data.
            2. Record - Write: Requests to write the content of the Detailed view to the selected record type in the selected object id. The Detailed checkbox must be selected in order for the data to be part of the write request. This allows narrowed modification of specific fields while preserving the other data values.
            3. Record - Add: Similar to the Write request, the Add command requests to write the specified Detailed content in the first available object id (first available location). The answer will indicate the location of the added object id.
            4. Record - Delete: Requests to delete the content of the specified object id range.
            5. Record - Get info: Request to retrieve the basic information related to the specified object record type. These information include the size of the record type in bytes (dword0), the maximum object id supported (dword2) and number of object id used (dword1). Note that the number of object id used feature is not supported by all of the object types. When supported, it represents the index+1 of the last object id used in the device. It should be used to narrow the range of object id to read. This range may includes some empty locations.
               

   2. The Detailed view shows the content of the Record type data or command that can be sent to the Atrium device target. This view always displays the content of the Object id Start specified in the Object type controller. The object id Detailed display can be switch between Basic to Advanced display at any time using the Basic/Advanced button located in the top-right corner of the Detailed display panel. The basic view usually represents the mandatory content to provide along with the Add a new Object id command.
      

      To help the understanding of an object type content, compare the data read from the Atrium SDK against the one read from the web page or the Atrium software.

   3. The History view shows all the transaction (rx/tx) exchanged with the Atrium device target so far. Click on any of transaction in the history view to visualize its content in the Packet detail view. Answers from the Atrium device target are marked with a result. The Atrium target device always answers with the same transaction id as the original request. It allows the software to bind the request with the corresponding answer. Multiple transactions can be sent within the same communication to the Atrium target device.
      
   4. The Packet detail view shows the content of the selected transaction in the history log. It represents the non-encrypted data that has been exchanged with the Atrium device target. If no content is displayed, select a transaction id in the history log to visualize its content.
      

   Want to add new Object id but don't know what type of information to fill in? Use the web interface or Atrium software to create a default Object id and then, read it back with the SDK to use it as a default template. Change the command from "Read" to "Add", modify the dedicated information (such as user name or card number) and send the Add command to the Atrium target device.

Related articles