Black Box Home Theater Server ACR1000A CTL API User Manual

ACR1000A-CTL API  
ServSwitchiPATH Manager API  
Application Programming Interface (API) Manual  
Order toll-free in the U.S.: Call 877-877-BBOX (outside U.S. call 724-746-5500)  
FREE technical support 24 hours a day, 7 days a week: Call 724-746-5500 or fax 724-746-0746  
Mailing address: Black Box Corporation, 1000 Park Drive, Lawrence, PA 15055-1018  
Customer  
Support  
Information  
 
ServSwitch iPATH Manager API Documentation  
API Documentation  
API version: 2  
Changelog  
v2 (IPATH v2.3) - added get_devices, get_channels, connect_channel, disconnect_channel. Updated version compatibility  
information.  
v1 (IPATH v1.3) - added login, logout, get_presets, connect_preset, disconnect_preset  
Methods  
login  
logout  
get_devices  
get_channels  
get_presets  
connect_channel  
connect_preset  
disconnect_channel  
disconnect_preset  
login  
This method was last updated in API version 1, and is compatible with API requests from version 1 onwards.  
The API will require a valid IPATH user's login credentials to be presented in the first request. The API will return an authentication  
code, which must be passed in all future requests. This authentication code can be re-used until a logout request is made, at  
which point the authentication code will no longer be valid.  
The concept of an “anonymous user” can apply to the API. If no login username and password are provided, the API will return  
an authentication token for the anonymous user (either the same one as for the OSD, or else an “anonymous API user” account  
can be created).  
Input parameters:  
- username  
- password  
- v (the IPATH API version this request is designed for)  
Output values:  
- timestamp - the current server time  
- version - the current API version number  
- token - an authentication code for future API requests  
- success  
NOTE: login examples are on the next page.  
724-746-5500 | blackbox.com  
Page 3  
 
ServSwitch iPATH Manager API Documentation  
Examples  
Input:  
/api/?v=1&method=login&username=xxxxx&password=xxxxx  
Output:  
<api_response>  
<version>1</version>  
<timestamp>2012-12-14 12:12:12</timestamp>  
<success>1</success>  
<token>5cf494a71c29e9465a57a81e0a2d602c</token>  
</api_response>  
or  
<api_response>  
<version>1</version>  
<timestamp>2012-12-14 12:12:12</timestamp>  
<success>0</success>  
<errors>  
<error>  
<code>2</code>  
<msg>Invalid username or password</msg>  
</error>  
</errors>  
</api_response>  
logout  
This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.  
The authentication token provided by the login function can be used until the logout function is called.  
Input parameters:  
- token  
- v (the IPATH API version this request is designed for)  
Output values:  
- timestamp - the current server time  
- success - 0 = fail, 1 = success  
Examples  
Input:  
/api/?method=logout&token=xxxxx&v=1  
Output:  
<api_response>  
<version>1</version>  
<timestamp>2011-02-04 15:24:15</time>  
<success>1</success>  
s</api_response>  
724-746-5500 | blackbox.com  
Page 4  
 
ServSwitch iPATH Manager API Documentation  
or  
<api_response>  
<version>1</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>0</success>  
<errors>  
<error>  
<code>3</code>  
<msg>Error logging out (you may already have logged out)</msg>  
</error>  
</errors>  
</api_response>  
get_devices  
This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.  
This function returns a list of devices.  
Input parameters:  
- token  
- v (the IPATH API version this request is designed for)  
- device_type ('rx' = receivers, 'tx' = transmitters. Default = 'rx')  
- filter_d_name (Optional. Device name search string)  
- filter_d_description (Optional. Device description search string)  
- filter_d_location (Optional. Device location search string)  
- sort (Optional. Sort results by 'name'/'description'/'location'. Default = 'name')  
- sort_dir (Optional. Sort direction for results 'asc'/'desc'. Default = 'asc')  
- status (Optional. '','outdated_iPATH_ip','rebooting','offline','outdated_firmware','invalid_backup_firmware','rebooting','upgrading'  
- show_all (Optional. If set and not blank, shows all receivers, not just those the logged-in user is permitted to use)  
- page (page number to start showing results for, default = 1)  
- results_per_page (number of results per page, default = 1000)  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success  
- page (page number)  
- results_per_page (number of results per page, default = unlimited)  
- total_devices - the total number of devices  
- count_devices - the number of devices on this page  
- for each device:  
- attribute: item (e.g. 17th device)  
- d_id (device id)  
- d_mac_address (device MAC address)  
- d_name (device name)  
- d_description (device description)  
- d_location (device location)  
- d_online (0 = offline, 1 = online, 2 = rebooting, 3 = factory_resetting, 4 = firmware_upgrading, 6 = running backup  
firmware)  
- d_type (rx, tx)  
724-746-5500 | blackbox.com  
Page 5  
 
ServSwitch iPATH Manager API Documentation  
- d_version (1 = ACR1000A, 2 = ACR1002A)  
- d_variant ('', 'b' = ACR1002A)  
- d_ip_address  
- d_configured (0 = no, 1 = yes)  
- d_valid_firmware (0 = no, 1 = yes)  
- d_valid_backup_firmware (0 = no, 1 = yes)  
- d_firmware (firmware version, e.g. 2.5.17879)  
- d_backup_firmware (backup firmware version)  
- d_date_added (Date device added to iPATH network e.g. 2012-07-13 22:17:22)  
The following property is only returned for transmitters:  
- count_transmitter_channels (the number of channels containing this transmitter)  
The following properties are only returned for receivers:  
- con_start_time (start time of last connection e.g. 2012-09-07 13:33:17)  
- con_end_time (empty if connection still active, else date/time the connection was ended e.g. 2012-09-07 13:33:17)  
- con_exclusive (0/1 - if the last connection is/was in exclusive mode)  
- con_control (0/1 - if the last connection has/had USB enabled)  
- u_username (username of the user who initiated the last connection)  
- u_id (user ID of the user who initiated the last connection)  
- c_name (name of the channel last connected)  
- count_receiver_groups (the number of receiver groups this receiver is a part of)  
- count_users (the number of users who have access to this receiver)  
Examples  
Input:  
/api/?v=2&method=get_devices&token=xxxxx  
/api/?v=2&method=get_devices&device_type=tx&page=2&results_per_page=3&token=xxxxx  
Output:  
<api_response>  
<version>2</version>  
<timestamp>2012-09-12 14:56:11</timestamp>  
<success>1</success>  
<page>2</page>  
<results_per_page>3</results_per_page>  
<total_devices>12</total_devices>  
<count_devices>3</count_devices>  
<devices>  
<device item="4">  
<d_id>170</d_id>  
<d_mac_address>00:0F:58:01:6E:3D</d_mac_address>  
<d_name>RX 123</d_name>  
<d_online>1</d_online>  
<d_type>rx</d_type>  
<d_version>2</d_version>  
<d_variant></d_variant>  
<d_ip_address>10.10.10.66</d_ip_address>  
<d_description></d_description>  
<d_location>Server Rack 3</d_location>  
<d_configured>1</d_configured>  
<d_valid_firmware>1</d_valid_firmware>  
724-746-5500 | blackbox.com  
Page 6  
 
ServSwitch iPATH Manager API Documentation  
<d_valid_backup_firmware>1</d_valid_backup_firmware>  
<d_firmware>2.3.16682</d_firmware>  
<d_backup_firmware>2.3.16682</d_backup_firmware>  
<d_date_added>2012-07-14 01:37:07</d_date_added>  
<con_exclusive>0</con_exclusive>  
<con_control>1</con_control>  
<con_start_time>2012-09-07 13:33:19</con_start_time>  
<con_end_time/>  
<u_username>admin</u_username>  
<u_id>1</u_id>  
<c_name>Channel 1</c_name>  
<count_receiver_groups>1</count_receiver_groups>  
<count_users>1</count_users>  
<custom_settings>0</custom_settings>  
</device>  
</devices>  
</api_response>  
<api_response>  
<version>2</version>  
<timestamp>2012-09-12 14:56:11</timestamp>  
<success>1</success>  
<page>1</page>  
<results_per_page>1</results_per_page>  
<total_devices>1</total_devices>  
<count_devices>1</count_devices>  
<devices>  
<device item="1">  
<d_id>64</d_id>  
<d_mac_address>00:0F:58:01:56:85</d_mac_address>  
<d_name>TX 456</d_name>  
<d_online>0</d_online>  
<d_type>tx</d_type>  
<d_version>1</d_version>  
<d_variant></d_variant>  
<d_ip_address>1.1.201.31</d_ip_address>  
<d_description></d_description>  
<d_location></d_location>  
<d_configured>1</d_configured>  
<d_valid_firmware>1</d_valid_firmware>  
<d_valid_backup_firmware>1</d_valid_backup_firmware>  
<d_firmware>2.1.15747</d_firmware>  
<d_backup_firmware>2.1.15747</d_backup_firmware>  
<d_date_added>2012-07-13 17:50:04</d_date_added>  
<count_transmitter_channels>3</count_transmitter_channels>  
<custom_settings>0  
</custom_settings>  
</device>  
</devices>  
</api_response>  
724-746-5500 | blackbox.com  
Page 7  
 
ServSwitch iPATH Manager API Documentation  
get_channels  
This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.  
This simple function returns a list of channels available to the authenticated user, for a specific receiver.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- page (page number to start showing results for, default = 1)  
- results_per_page (number of results per page, default = 1000)  
- device_id (ID of the receiver that this channel will be connected to. Recommended to ensure full checks for connection mode  
availability.  
- filter_c_name (channel name search string)  
- filter_c_description (channel description search string)  
- filter_c_location (channel location search string)  
- filter_favorites (set this non-empty to only show a user's favorites)  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success  
- page (page number)  
- results_per_page (number of results per page, default = unlimited)  
- count_channels - the number of channels on this page, available to the authenticated user  
- for each channel:  
- attribute: item (e.g. 17th channel)  
- c_id (channel id)  
- c_name (channel name)  
- c_description (channel description)  
- c_location (channel location)  
- c_favorite (true if this channel is in the user's favorites, 0-9 if it's a numbered shortcut)  
- view_button (disabled/enabled/hidden - whether the user can connect to the preset in view-only mode.  
disabled = no, because something is in use by someone else. hidden = never. enabled = yes.  
If the device_id of the proposed receiver to be used in the connection is not provided, this will not necessarily be an  
accurate indication of whether other connections may actually interfere)  
- shared_button (disabled/enabled/hidden - as above, but in shared mode)  
- exclusive_button (disabled/enabled/hidden - as above, but in exclusive mode)  
Examples  
Input:  
/api/?v=2&method=get_channels&token=xxxxx  
Output:  
<api_response>  
<version>2</version>  
<timestamp>2012-12-14 12:12:12</timestamp>  
<success>1</success>  
<page>1</page>  
<results_per_page>10</results_per_page>  
724-746-5500 | blackbox.com  
Page 8  
 
ServSwitch iPATH Manager API Documentation  
<count_channels>2</count_channels>  
<channel item="1">  
<c_id>3</c_id>  
<c_name>Channel 1</c_name>  
<c_description>Description for Channel 1</c_description>  
<c_location>Location of Channel 1</c_location>  
<c_favorite>false</c_favorite>  
<view_button>disabled</view_button>  
<shared_button>disabled</shared_button>  
<exclusive_button>disabled</exclusive_button>  
</channel>  
<channel item="2">  
<c_id>5</c_id>  
<c_name>Channel 2</c_name>  
<c_description>Description for Channel 2</c_description>  
<c_location>Location of Channel 2</c_location>  
<c_favorite>2</c_favorite>  
<view_button>disabled</view_button>  
<shared_button>enabled</shared_button>  
<exclusive_button>hidden</exclusive_button>  
</channel>  
</api_response>  
get_presets  
This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.  
This simple function returns a list of presets available to the authenticated user.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- results_per_page (number of results per page, default = 1000)  
- page (page number to start showing results for, default = 1)  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success  
- page (page number)  
- results_per_page (number of results per page, default = unlimited)  
- total_presets - the total number of presets available to the authenticaed user  
- count_presets - the number of presets on this page, available to the authenticated user  
- for each connection_preset:  
- attribute: item (e.g. 17th preset)  
- cp_id (preset id)  
- cp_name (preset name)  
- cp_description (preset description)  
- cp_pairs (the number of channel-receiver pairs in this preset)  
- problem_cp_pairs (the number of channel-receiver pairs that are misconfigured  
(e.g. receiver offline, receiver not defined)  
724-746-5500 | blackbox.com  
Page 9  
 
ServSwitch iPATH Manager API Documentation  
- count_active_cp (the number of channel-receiver pairs in this preset that are already connected)  
- connected_rx_count (the number of receivers in this preset that are already connected)  
- view_button (disabled/enabled/hidden - whether the user can connect to the preset in view-only mode.  
disabled = no, because something is in use by someone else. hidden = never. enabled = yes)  
- shared_button (disabled/enabled/hidden - as above, but in shared mode)  
- exclusive_button (disabled/enabled/hidden - as above, but in exclusive mode)  
Examples  
Input:  
/api/?v=1&method=get_presets&token=xxxxx  
Output:  
<api_response>  
<version>1</version>  
<timestamp>2012-12-14 12:12:12</timestamp>  
<success>1</success>  
<page>1</page>  
<results_per_page>10</results_per_page>  
<total_presets>2</total_presets>  
<count_presets>2</count_presets>  
<connection_preset item="1">  
<cp_id>3</cp_id>  
<cp_name>Preset 1</cp_name>  
<cp_description>Description for Preset 1</cp_description>  
<cp_pairs>1</cp_pairs>  
<problem_cp_pairs/>  
<count_active_cp/>  
<connected_rx_count>1</connected_rx_count>  
<view_button>disabled</view_button>  
<shared_button>disabled</shared_button>  
<exclusive_button>disabled</exclusive_button>  
</connection_preset>  
<connection_preset item="2">  
<cp_id>4</cp_id>  
<cp_name>Preset 2</cp_name>  
<cp_description>Description for Preset 2</cp_description>  
<cp_pairs>2</cp_pairs>  
<problem_cp_pairs/>  
<count_active_cp/>  
<connected_rx_count/>  
<view_button>enabled</view_button>  
<shared_button>hidden</shared_button>  
<exclusive_button>hidden</exclusive_button>  
</connection_preset>  
</api_response>  
724-746-5500 | blackbox.com  
Page 10  
 
ServSwitch iPATH Manager API Documentation  
connect_channel  
This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.  
This simple function connects a receiver to a channel.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- c_id - the ID of the channel (acquired from get_channels)  
- rx_id - the ID of the receiver (acquired from get_receivers)  
- view_only (optional, 0/1 - defaults to 0)  
- exclusive (optional, 0/1 - defaults to 0)  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success (0 = fail, 1 = success)  
- errors (optional, if anything went wrong with connecting the channel)  
Examples  
Input:  
/api/?v=2&method=connect_channel&token=xxxxx&c_id=1&rx_id=2&exclusive=1  
Output:  
<api_response>  
<version>2</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>1</success>  
</api_response>  
or  
<api_response>  
<version>2</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>0</success>  
<errors>  
<error>  
<code>231</code>  
<msg>ERROR - exclusive connection not available</msg>  
</error>  
</errors>  
</api_response>  
724-746-5500 | blackbox.com  
Page 11  
 
ServSwitch iPATH Manager API Documentation  
connect_preset  
This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.  
This simple function connects all channel-receiver pairs in a preset.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- id - the ID of the preset (acquired from get_presets)  
- view_only (optional, 0/1 - defaults to 0)  
- exclusive (optional, 0/1 - defaults to 0)  
- force - whether to ignore errors with some of the preset's pairs or not  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success (0 = fail, 1 = success)  
- errors (optional, if anything went wrong with connecting the presets)  
Examples  
Input:  
/api/?v=1&method=connect_preset&token=xxxxx&id=1&force=1  
Output:  
<api_response>  
<version>1</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>1</success>  
</api_response>  
or  
<api_response>  
<version>1</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>0</success>  
<errors>  
<error>  
<code>210</code>  
<msg>A Receiver is in use by another User</msg>  
</error>  
</errors>  
</api_response>  
724-746-5500 | blackbox.com  
Page 12  
 
ServSwitch iPATH Manager API Documentation  
disconnect_channel  
This method was last updated in API version 2 and is compatible with API requests from version 2 onwards.  
This function disconnects a receiver, a number of receivers, or all connected receivers.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- rx_id (ID(s) of the receiver, as an integer, or comma-separated set of integers. Optional.  
- force - whether to disconnect existing connections by other users, or for off-line receivers  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success (0 = fail, 1 = success)  
- errors (if anything failed, details are returned here)  
Examples  
Input:  
/api/?v=2&method=disconnect_channel&token=xxxxx&rx_id=1  
/api/?v=2&method=disconnect_channel&token=xxxxx&rx_id=1,2,3  
/api/?v=2&method=disconnect_channel&token=xxxxx&force=1  
Output:  
<api_response>  
<version>2</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>1</success>  
</api_response>  
disconnect_preset  
This method was last updated in API version 1 and is compatible with API requests from version 1 onwards.  
This function disconnects all channel-receiver pairs in a preset, or disconnects ALL connections in the whole Agility network.  
Input parameters:  
- token  
- v (the iPATH API version this request is designed for)  
- id (optional. If not supplied, all connections will be ended)  
- force - whether to ignore errors with some of the preset‘s pairs or not  
Output values:  
- version - the current API version number  
- timestamp - the current server time  
- success (0 = fail, 1 = success)  
- errors (if anything failed, details are returned here)  
724-746-5500 | blackbox.com  
Page 13  
 
ServSwitch iPATH Manager API Documentation  
Examples  
Input:  
/api/?v=1&method=disconnect_preset&token=xxxxx&id=1&force=1  
Output:  
<api_response>  
<version>1</version>  
<timestamp>2012-12-12 12:12:12</timestamp>  
<success>1</success>  
</api_response>  
724-746-5500 | blackbox.com  
Page 14  
 
NOTES  
724-746-5500 | blackbox.com  
Page 15  
 
Black Box Tech Support: FREE! Live. 24/7.  
Tech support the  
way it should be.  
Great tech support is just 30 seconds away at 724-746-5500 or blackbox.com.  
About Black Box  
Black Box provides an extensive range of networking and infrastructure products. You’ll find everything from cabinets and racks  
and power and surge protection products to media converters and Ethernet switches all supported by free, live 24/7 Tech support  
available in 30 seconds or less.  
© Copyright 2013. Black Box Corporation. All rights reserved. Black Box® and the Double Diamond logo are registered trademarks, and ServSwitch is a  
trademark, of BB Technologies, Inc. Any third-party trademarks appearing in this manual are acknowledged to be the property of their respective owners.  
ACR1000A-CTL API, version 1  
724-746-5500 | blackbox.com  
 

Belkin Network Card F5D7010 User Manual
Belkin Switch F1U123 KIT User Manual
Blue Rhino Gas Grill GBC621CR C User Manual
Bretford Indoor Furnishings RHOMBII User Manual
Breville Espresso Maker ESPRESSO MACHINE User Manual
Briggs Stratton Lawn Mower SZC User Manual
Brother All in One Printer FAX 1170 User Manual
Cabletron Systems Switch 924TXG User Manual
Casio Calculator FC 200V User Manual
Christie Digital Systems Projector 38 VIV207 01 User Manual