Академический Документы
Профессиональный Документы
Культура Документы
Introduction ............................................................................................................. 2
Terminology .................................................................................................... 2
Application Programming Interface (API) Options ........................................................... 2
Command Line Interfaces (CLIs) ........................................................................ 2
CORBA APIs .................................................................................................... 2
CORBA Overview ................................................................................... 2
CORBA Advantages ................................................................................ 3
Broadband Command Center CORBA API IDL File Listing ............................. 3
CORBA API Comparison with CLI ........................................................................ 4
API Documentation........................................................................................... 4
Login and Logout Before API Execution ......................................................................... 4
Subscriber Provisioning via the MPS CORBA API ............................................................. 5
Database Tables............................................................................................... 5
Creating, Updating, or Deleting Database Records................................................. 6
DatabaseControl API .............................................................................. 6
DeviceControl API to Allow Device Resets .................................................. 6
Lookup Keys for Subscriber-Device Association .......................................... 6
Replacing a Device................................................................................. 7
Search and Retrieval of Database Records ........................................................... 7
Forcing a Reset on a Modem or MTA.................................................................... 7
Identifying Which Device is Currently Using an IP Address...................................... 7
Identifying IP Addresses Currently Assigned to a Device ........................................ 8
Retrieving Active Lease for a Modem and All Connected CPE ................................... 8
Provisioning and Managing Static IP Addresses ..................................................... 9
Auto-Provisioning Process ....................................................................... 9
Auto-Provisioning Static IP Addresses With Data Service Records................ 10
Explicitly Managing Static IP Addresses ................................................... 10
Subscriber Provisioning via the CLI ............................................................................ 11
References ............................................................................................................. 11
Introduction
Broadband Command Center (BCC) software is a set of network services that work together to
provision DOCSIS cable modems, PacketCable and SIP MTAs, and customer premises equipment
(CPE) on a broadband network. The network services include:
• DHCP
• DNS
• TFTP
• Time of Day
• MPS (Multimedia Provisioning Service)
BCC software is often integrated with a customer care center, billing, or OSS system to provision and
manage subscribers or subscriber devices. This document gives an overview of the Application
Programming Interfaces (APIs) that you can use to integrate BCC 5.1 with those systems.
Before learning more about the APIs, you should be familiar with BCC software operation, as described
in Incognito Software’s “BCC Provisioning Overview” document. This will greatly increase your
understanding of the APIs.
Terminology
CPE: Customer premises equipment – any device that accesses the Internet from the
customer premises and sits “behind” a modem or MTA. (The CPE interfaces with
a broadband provider’s network through the modem or MTA.)
CSR: Customer service representative.
eMTA: Embedded MTA, which is a single physical device that contains both a DOCSIS
cable modem and a PacketCable MTA.
MPS: Multimedia Provisioning Service. One of the network services included with BCC
software, and used to provision data and voice services for subscribers.
CORBA APIs
Each BCC service supports a number of CORBA APIs.
CORBA Overview
CORBA (Common Object Request Broker Architecture) is an open specification developed by the
Object Management Group (OMG, http://www.corba.org/) to enable computer applications to work
with one another. One CORBA-based program can interoperate with another CORBA-based program
on a different computer, operating system, language, or network.
CORBA takes objects from one software program and “wraps” them so they can be called from other
programs. (Objects are program components designed to receive, send, or process data.)
A software vendor can publish a CORBA API through one or more Interface Definition Language (IDL)
files. The IDL file describes the interfaces offered by objects inside a program, and how they are to be
used by other programs, by “mapping” them to a specific language such as C++ or Java.
To make use of an IDL file, you must run it in conjunction with a software library known as a CORBA
ORB (Object Request Broker), which allows program calls from one computer to another over a
network. The CORBA ORB typically comes with an “IDL compiler,” which translates the objects defined
in the IDL file into a set of source-code files specific to the required programming language. You can
then use the generated source code to make calls to the other program.
There are many CORBA ORBs available, sold commercially or as freeware, for many different
programming languages. The following two CORBA ORBs are excellent freeware implementations:
CORBA Advantages
• Programming language independence: A client application does not need to use the same
programming language as the service application. It can use any programming language for
which a CORBA ORB exists. Languages include: Java, C, C++, SmallTalk, Python, Lisp, ADA,
COBOL
• Platform independence: A client application can run on a different platform or operating
system from the service application.
• Compile time type checking: Unlike XML, CORBA enforces type checking to catch many
errors at compile time.
• Performance: CORBA can compress data for higher performance, unlike XML, which always
represents data as text.
BCC Service CORBA API IDL File Included IDL File Description
CORBA CLI
Performance Fast. Typically you can add 1000 Slow when not used in interactive mode.
subscribers and modems to the In this case, you may only be able to add
system per second using the 4 subscribers and modems to the system
CORBA API. per second. This mode requires the
following steps for each command:
• Operating system loads the CLI
• CLI connects and logs into the service
• CLI executes the APIs
• CLI logs out and disconnects from the
service
• Operating system unloads the CLI
Error Error code is directly returned to An error message is output to the console,
Reporting the caller. which must be parsed.
The error code can not always be returned
by the CLI as an exit code because many
operating systems or Unix shells only allow
an exit code in the range of 0–255, while
many error codes returned by BCC
services are greater than 255.
Knowledge Knowledge of CORBA. Knowledge of how to use a programming
Requirement The complexity of using CORBA is or script language to execute a command
not high if you have experience line interface, and possibly parse console
programming with CORBA. output.
API Documentation
For additional details on any API, please read the comments for the API in the appropriate CORBA IDL
file. The SDK includes the same help documentation in HTML format.
C++-based sample code for logging into the DHCP service is located in the SDK at:
DHCP\CORBA-API\samples\clientprovsample-c++\ipcsecurity.cpp
Note: the mechanisms for logging into the DHCP and MPS services are the same except for the CORBA
port (9998 for DHCP and 9997 for MPS).
Database Tables
As defined in the DPCmdrService.idl IDL file, the MPS service contains database tables for subscriber
and device data. Device data is stored in the form of “service records” (DataService, VoiceService, and
CPEDevice), which are correlated with specific subscribers through lookup keys.
Subscriber
-Name
-Account ID
-Description
-Organization
-Department
-Office
-Email Addresses
-Phone Numbers
-Mailing Address
-Notes
-Creation Time
-Last Modified Time
-Lookup Key
1 1
DataService VoiceService
*
-Name -Name
-Description -Description
-MAC Address * -MAC Address
-FQDN -SNMP Version
-Max # of CPEs -FQDN
-ClientClasses -Enabled
-Creation Time -Lines
-Last Modified Time -Creation Time
-Last Modified Time
0..1
1
CPEDevice
-Name
*
-Description
-MAC Address *
-Modem Line Configuration
-Client Classes -Enabled
-Static Addresses -Endpoint Index
-Creation Time -CMS FQDN
-Last Modified Time -CMS Port
Parameters:
AuthToken The valid login session token acquired during service login.
Command The “command” parameter, which indicates whether to add (CC_ADD), update
(CC_SET), retrieve (CC_GET) or delete (CC_DELETE) a record.
Deleting a subscriber record will automatically delete any devices associated with that subscriber.
Java-based sample code for adding, updating and deleting subscriber records appears in the SDK at:
MPS\CORBA-API\samples\subscriberprovisioning\src\mpssample\com\incognito\mpssample\SubscriberManager.java
device, you can associate it with a particular subscriber by simply setting the subscriberDataID field to
the value of the subscriber’s r_ID field.
If the subscriberDataID field for a device is set to all-zero bytes, then the device does not belong to
any subscriber and is considered, in this context, to be “unsubscribed.” The system still recognizes it,
though, and still provisions it with the services associated with the device.
Replacing a Device
Replacing a device simply means changing its MAC address. For example, to replace a cable modem,
you would typically:
• Retrieve the current DataServiceV3 record for the old cable modem
• Set the “cmMacAddress” field to the MAC address of the new cable modem.
• Call the deviceControl API with the “CC_SET” command to update the modem’s data service
record with the new MAC address. All instances of the old cable modem MAC address are
automatically replaced with the new cable modem MAC address in all configurations on the
MPS and DHCP service.
For example, you can retrieve a subscriber record (including its r_ID member) by performing a search
for the subscriber name, account ID, device MAC address, or other subscriber data.
Java-based sample code for searching for subscribers by name, description, account ID, device MAC
address, or IP address appears in the SDK at:
MPS\CORBA-API\samples\subscriberprovisioning\src\mpssample\com\incognito\mpssample\SubscriberSearch.java
CableModemMacAddress The MAC address of the cable modem to which the device is connected.
If the IP address belongs to the cable modem itself, then
deviceMacAddress and cableModemMacAddress will have the same value.
This value is only known to the system, and will therefore only be
returned if the CMTS is operating in DOCSIS-compliant mode and is
inserting the cable modem MAC addresses as a “remote ID” (DHCP
option 82.2) into the device’s DHCP packets.
Returned IP address lease data can include the following, depending on the lease configuration:
Returned SNMP data can include the following, depending on the modem configuration:
Auto-Provisioning Process
BCC software can auto-provision static IP addresses for CPE behind a cable modem using this process:
• The DHCP service looks up the lease for the cable modem.
• The DHCP determines which CMTS is responsible for inserting the GIADDR (gateway IP
address) into the cable modem DHCP packets.
• The DHCP service determines which other subnets are configured on the cable interface for
this GIADDR.
• The DHCP service evaluates the “rule tree” to determine which of the subnets found in step 3
can allocate IP addresses to devices behind this cable modem.
• The DHCP service looks for one or more free contiguous IP addresses from the list of
subscribers found in step 4, and converts them into “remote ID”-based static addresses or
“remote ID and MAC address”-based static addresses.
As a result of the above process, auto-provisioning only works under the following conditions:
• The cable modem must currently have a lease.
• The CMTS must be configured to insert the primary interface into all DHCP packets.
• The DHCP service must be correctly configured with a CMTS Settings record for each CMTS,
and with the gateway IP addresses configured and mapped to the appropriate “serviced
networks” for each cable interface.
The resulting static IP address will be based on “CPE remote ID,” which is actually the cable modem
MAC address. The DHCP service assigns the static IP address to the first device that comes online
behind the cable modem. If multiple static IP addresses exist for the same cable modem, then the
DHCP service assigns the lowest static IP address to the first device that comes online behind the
cable modem, and so on.
In the case of multiple static IP addresses per cable modem, the CPE behind the modem can swap
static IP addresses if those CPE release their IP addresses and then attempt to acquire an IP address
from the DHCP service in the reverse order.
Device The (optional) CPE MAC address that needs a static IP address. If you don’t
supply a value for this parameter (length is set to 0), then you must provide
a value for the RemoteID parameter so that the static IP address will be
based on the remote ID or the remote ID + CPE MAC address (with a blank
CPE MAC address), depending on service configuration.
RemoteID The remote ID for the static IP address, typically the MAC address of the
cable modem to which the CPE is connected. If you don’t supply a value for
this parameter (length is set to 0), then you must supply values for the
Device and IPAddress parameters so that the static IP address will be MAC
address-based.
IPAddress The static IP address required. If you don’t supply a value for this parameter,
then you must supply a value for RemoteID using the MAC address of a
DOCSIS cable modem, and this will be the IP address that BCC will auto-
provision. When the call is successfully returned, IPAddress holds the value of
the auto-provisioned IP address.
To un-provision static IP addresses created with the above provisionStaticAddress API, you must use
the following unprovisionStaticAddress API defined in DPCmdrService.idl.
ErrorCode unprovisionStaticAddress( in AuthorizationToken authToken,
in MACAddress device,
in MACAddress remoteID,
in IPAddress staticIPAddress);
Parameters:
Device The MAC address of the device for which static IP address(es) needs to be
deleted.
RemoteID The remote ID for which the static IP address needs to be deleted.
IPAdress The IP address for which the static IP address needs to be deleted. If you
don’t supply a value for this parameter, then ALL static addresses
matching the device and/or remote ID fields will be deleted.
Note that the above API can delete multiple static address records, depending on which parameters
are supplied with data. For example, if you pass only a remoteID to the call, all static IP addresses
associated with that remoteID will be deleted. If you pass the IP address parameter to the call, then
only one static address is deleted since there is only one static address for each IP address.
References
DOCSIS 1.0 Radio Frequency Interface Specification, November 6, 2001, Cable Television
Laboratories, Inc., http://www.cablemodem.com/
DOCSIS 1.1 Radio Frequency Interface Specification, SP-RFIv1.1-I10-030730, July 30, 2003, Cable
Television Laboratories, Inc., http://www.cablemodem.com/
DOCSIS 2.0 Radio Frequency Interface Specification, CM-SP-RFIv2.0-I08-050408, April 8, 2005, Cable
Television Laboratories, Inc., http://www.cablemodem.com/
DOCSIS Cable Device MIB, RFC 2669, August 1999, M. St. Johns, Ed.,
PacketCable MTA Device Provisioning Specification, PKT-SP-PROV-I10-040730, July 30, 2004, Cable
Television Laboratories, Inc., http://www.packetcable.com/
PacketCable MTA MIB Specification, PKT-SP-MIB-MTA-I09-040402, April 02, 2004, Cable Television
Laboratories, Inc., http://www.packetcable.com/
BCC Provisioning Overview, Incognito SDK 5.1, April 11, 2006, Incognito Software Inc.,
http://www.incognito.com/
Contact:
Incognito Software Inc.
Phone: 604.688.4332 or US/Canada toll free 800.877.1856
Fax: 604.688.4339
Email: sales@incognito.com
Web: http://www.incognito.com