xAPI Guide > Using SSH with xAPI

A collaboration device's xAPI is accessible from a simple SSH connection, which lets you interact with xAPI from a 'command line' (this is how many third-party control systems interact with xAPI, for example, Crestron/AMX). From there you can request status information, update the device configuration, listen for events, and send commands to your device.

anchorPrerequisites and Configuration

anchorBasic Commands Via SSH

1. Log in to the device via SSH:

   For Mac and Linux users: from a terminal, open a SSH connection to your device by entering:

   ssh <device_ip> -l integrator
   

   For Windows users: launch PuTTY (see this tutorial's BYOD/pre-requisites), start a new session with your device's ip address, and click Open. Enter your integrator user credentials:

   

2. Use the xstatus command to retrieve the device's standby state. In the SSH session, enter:

   xstatus /Standby
   

   and check that the displayed info corresponds to the same information in the web interface:

   *s Standby State: Standby
   ** end
   

   Note that the *s prefix in the response stands for 'Status information'. The SSH interface supports helpful command completion at any point by pressing Tab.

3. Next, to view the various attributes of the device's standby configuration, enter:

       xconfiguration Standby
   

   which should return something like:

    *c xConfiguration Standby BootAction: DefaultCameraPosition
    *c xConfiguration Standby Control: On
    *c xConfiguration Standby Delay: 10
    *c xConfiguration Standby StandbyAction: PrivacyPosition
    *c xConfiguration Standby WakeupAction: RestoreCameraPosition
    *c xConfiguration Standby WakeupOnMotionDetection: On
    ** end
   

anchorUse xcommands to Change the State of the Device

1. Make sure your device is in standby state. You can do this manually via the web admin, under Settings > Standby, and in Configuration / Standby, set Control to on and click Save.

2. From SSH, use a xcommand request to disable standby mode:

   xcommand Standby Deactivate
   

   which will return with:

   *r StandbyDeactivateResult (status=OK):
   ** end
   

3. Visually confirm that your device has left standby mode

   Note: you can remotely view what's on the screen of the device or its Touch10 controller via the web interface, under Issues and Diagnostics > User Interface Screenshots. If your device does not have a main screen attached (for example, Sandbox), view the Touch10 interface.

4. Next, let's use xstatus to confirm the standby status:

   xstatus Standby
   

   which should return something like:

   *s Standby State: Halfwake
   ** end
   

anchorxAPI Notifications

xAPI provides the ability to register for feedback notifications generated by the device. Feedback can be anything from a change in standby status, or an outgoing call being placed, or a change in the number of faces detected by the camera.

A device in operation may produce a very high number of different notifications in production operation, including many your application may not care about. xAPI provides the ability to indicate very specific or very general feedback filters, so that you receive only the notifications you are interested in.

Let's see how this works:

1. First, let's put the device in standby mode (if it's not already.) Enter:

   xcommand Standby Activate
   

2. Next, let's register to receive feedback notifications when the standby status changes:

   xfeedback register /Status/Standby
   

3. Finally, turn standby mode off with an xcommand:

   xcommand Standby Deactivate
   

4. Check to see that the following feedback message is automatically sent to your SSH session:

   *s Standby State: Off
   ** end
   

   If you wait another 5 minutes (or whatever delay you configured in the previous step), you would likely see new notifications flying by as shown below:

   *s Standby State: EnteringStandby
   ** end
   *s Standby State: Standby
   ** end
   

   Moreover, if the WakeupOnMotionDetection feature is enabled and you leave/re-enter the room, you might see this extra event:

   *s Standby State: Halfwake
   ** end
   

anchorGoing further

The CE device 'T-Shell' xAPI command line environment provides auto-completion functionality, which can be a good way to easily check command syntax or even explore all the possible commands and options available.

For example, you can execute a base command - like xstatus by itself, which results in a print-out listing of all the available options and sub-options under that command.

At your own pace, try the following commands, just on their own, to see what happens:

• xstatus
• xconfiguration

What could you do with the information provided? Feel fry to try out some of the options for each!

The scope of events you receive can be narrowed or widened depending on the 'path' you provide to the xfeedback register command.

Try entering xfeedback register /Status to listen to all status changes, or simply xfeedback register / to listen to every type of event, system wide. Then perform various interactions with your device such as turning up or down the volume, or initiating a call. As the xfeedback events can get pretty numerous/verbose, make sure to type xfeedback deregisterall to turn off all event registrations when you're finished.

anchorUSB device events

If your system is running CE 9.6+, you can plug a USB keyboard into the device's base (Room and DX series), and receive events corresponding to key press/release activity:

1. Enable USB device event detection by logging into your device via SSH and running the following command:

   xConfiguration Peripherals InputDevice Mode: On
   

2. Type a few keys on the connected keyboard and you should see 'Key' (key identifier), 'Code' (numerical key code), and 'Type' (pressed or released) events appearing in the terminal:

   *e UserInterface InputDevice Key Action Key: KEY_O
   *e UserInterface InputDevice Key Action Code: 24
   *e UserInterface InputDevice Key Action Type: Pressed
   ** end
   *e UserInterface InputDevice Key Action Key: KEY_O
   *e UserInterface InputDevice Key ActionCode: 24
   *e UserInterface InputDevice Key Action Type: Released    
   ** end
   

anchorNext Steps

In essence, the xAPI is a bi-directional interface that lets you check your device state, modify configuration settings, register for real-time events, and take actions by sending commands.

These actions can be taken from the physical device controls (or Touch10), its web interface, or SSH.

Next, we will talk about an additional avenue for accessing xAPI we haven't yet covered: via HTTP.