Cisco Prime Home Device Driver Mapping Tool July 2013 Cisco Systems, Inc. www.cisco.com Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on the Cisco website at www.cisco.com/go/offices Text Part Number: OL- 30154-01
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING,WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental. Cisco Prime Home Device Driver Mapping Tool 1999 2013 Cisco Systems, Inc. All rights reserved.
Table of Contents Introduction... 4 Scope... 4 Intended Audience... 4 System Requirements... 4 Purpose of the Tool... 4 Steps for Testing... 4 Preparing Your Device... 4 Testing Your Device... 7 Communicating the Results to Cisco... 9 Tips to Expedite Testing... 11 Warning Against the Use of Legacy Drivers... 11 New Firmware for an Existing Device... 11 Increase the Logging Level... 11 OL- 30154-01 3
Introduction Scope This guide describes the Device Driver Mapping tool, an optional feature for the Cisco Prime Home management platform. Intended Audience The primary audience for this guide is device manufacturers, development partners, and Cisco Prime Home customer staff who specialize in customer premises device interoperability issues. System Requirements The Device Driver Mapping tool is included in Cisco Prime Home 5.1.1 and later.! This tool is a feature of the Cisco Prime Home management platform. If you need access to Prime Home, contact prime- home- interop@cisco.com. Purpose of the Tool The Device Driver Mapping tool facilitates limited testing of your device against an inventory of existing drivers. The test results can be sent to Cisco in the form of a temporary device class configuration, providing Cisco interoperability engineers with the data required to develop the custom device class configuration or drivers for your device to interface with Prime Home. If the CWMP management client is implemented according to the TR- 098 standard, the Prime Home standard drivers should provide some or all of the functionality to support your new, uncertified device. Existing drivers for other devices may also provide some or all functionality required to support your new, uncertified device if it does not closely follow the standards assumed by existing drivers. Steps for Testing Preparing Your Device 1. If necessary, contact prime- home- interop@cisco.com for access to the Device Driver Mapping tool (via a testing instance of Prime Home). 2. Cisco provides you with an ACS management URL for a testing instance of Prime Home. Add the URL and the following ACS parameters to the device to be tested: ACS URL: http://yourprimehometest.acs.clearaccess.com/ ACS Username: <blank> ACS Password: <blank> Connection Request Username: <blank> Connection Request Password: <blank> OL- 30154-01 4
Periodic Inform: enable Inform Interval: 180 seconds 3. Connect the device to a live internet connection. Test your connection by browsing to the management URL from a computer connected via the broadband you intend to use. A successful connection returns a message similar to the following: After your device completes its initial contact session with Prime Home (no longer than 1 to 2 minutes), the device is searchable in Prime Home. You will see the device s manufacturer, model, and serial number listed on the Prime Home Customer Support page, as in the following example for a SmartRG SR500: 4. Log into Prime Home using the instructions you acquired in Step 1. 5. From the landing page, enter the serial number of your device in the Search field; then, select the device from the search results. If you select a device in Prime Home for which no device class configuration exists, you receive the following message: OL- 30154-01 5
This message indicates that Prime Home has no drivers loaded to support the device. This is expected behavior. OL- 30154-01 6
Testing Your Device 1. From the left navigation sidebar, expand the Advanced menu and select Driver Mapping. The central pane of the screen contains a simple table. The left column lists the applications supported by this instance of Prime Home. The right column lists the drivers that are mapped to the applications. Upon first use, no mappings are created, and the right column is blank. Subsequent visits to the Device Driver Mapping tool display remnants of the driver selections made in previous sessions. Use the Clear All Selected Drivers function to the right of the Driver column to begin subsequent sessions with a clean slate. 2. Click the Override button. The Override button lets you select an available driver for each application that you want to test. It is not necessary to make a selection for every application. Select only the applications for which you want to achieve interoperability. OL- 30154-01 7
While legacy drivers are available for testing with many applications, do not use them for Prime Home 5.x platform interoperability. Legacy drivers are a last resort if the non- legacy drivers do not work. Note: The procedure for mapping drivers to a device requires an understanding of the application as well as the requirements and behavior of each driver. The Prime Home Compatible Wiki describes each application and driver. Also included are test plans for validating the management of each application, as well as guidance on best practices and things to avoid. Visit the wiki at http://developer.cisco.com/web/phc/wiki. 3. After making your device driver selections, click the Apply button. 4. At the prompt to save, click Save. After the save process completes, a yellow banner notifies you that the device now has a device class override. The banner prompts you to refresh the page for the new override settings to take effect. The message This device has not been verified as compatible by the service provider" is cleared because a device class override is in place. In place of the message, standard navigation is available in the applications for which you selected drivers. For example, if you selected a driver for Wi- Fi, that application is now available in the left navigation bar. 5. You can now interact with the device via the Prime Home UI. For example, if you selected a driver for Wi- Fi, you can set a channel, name the SSID, select a security type, and so on. 6. Click Save and then confirm that the device is operating as expected. Note that the existing drivers you selected might not achieve full interoperability. Make a note of the specific behaviors and Event Log messages that are undesirable. OL- 30154-01 8
Note: Due to application interdependency issues, there is a preferred order in which to test application/driver associations for new devices. The recommended sequence is: 1. ManagementServer 2. STUN (if applicable) 3. ManagementServerStatus 4. WANDevices 5. WANInterfaces 6. DeviceInfo 7. DeviceStats Proceed with testing any additional applications as needed. 7. If there are no apparent errors while interacting with an application, follow the test plan for that application as documented on the Prime Home Compatible Wiki. 8. Once the test cases for an application pass successfully, repeat these steps as necessary for the remaining applications you require. Communicating the Results to Cisco Having tested the available drivers and confirmed which drivers provide optimal usability of the device, email the dynamic device class configuration to prime- home- interop@cisco.com. Verify that there are no outstanding changes that have not been saved. 1. The device class details appear when you click the Show Exportable List link to the right of the driver selection menus. 2. A block of text appears. Select and copy all of this text. You might need to scroll down in the text box to capture all of the drivers listed. OL- 30154-01 9
3. Email the following results to prime- home- interop@cisco.com: If applicable, include in the subject line your invoice number relevant to interop engagement fees. The override list text as pictured in the preceding example. Your observations of specific functions that the standard drivers did not perform correctly. Your Interop Engagement Request form. OL- 30154-01 10
Tips to Expedite Testing Warning Against the Use of Legacy Drivers Do not use legacy drivers when testing compatibility with a new device. Legacy drivers generally do not validate that a device is behaving as expected. On devices that legacy drivers do not support, there are many cases where they may appear to work but silently fail without setting the application to an error state or raising any warning or error messages. For more information, see the Legacy Drivers page on the Prime Home Compatible wiki. New Firmware for an Existing Device In the case of a new firmware version for an existing device that previously worked with Prime Home, use the drivers mapped for a device running the old firmware as a starting point while testing the new firmware. Increase the Logging Level The Event Log provides valuable testing insight. The default logging level is set to Info. The Debug level is necessary to ensure that messages from the driver are seen; however, the Network level is recommended. At the Network level, the available SOAP messaging can be revealing when the device returns a fault response. Also revealed are the specific parameters that might be responsible for the error. 1. From the left navigation sidebar, expand the Advanced menu and select Event Logs. OL- 30154-01 11
2. Under the Configure Logging Detail heading, select the desired logging level. 3. When testing is complete, return the logging level to Info. OL- 30154-01 12