Pelco Developer Network (PDN)

Managing Systems and the Device Cache

The Pelco SDK Administrator object allows an application to manage systems and the device cache. These systems may represent an Endura system, a Pelco Aggregation system, or a Pelco Edge Device system. This article shows how to create and manage an edge device system and an Endura system, and how to clear the device cache.
 

Different Types of Systems

An edge device system is an arbitrary set of cameras or other devices residing in a virtual container (the “system”). The devices can be any Pelco cameras accessible on the network. These ad hoc systems can meet a specific need without requiring a change in network topology or reconfiguration of hardware.
 
An Endura system has an associated System Manager with attached devices. 
 
 
Information for both edge device and Endura systems is maintained similarly in the device cache. One difference is that because the edge device system is transient and created on-the-fly, its entries are not dependent on the discovery process associated with an Endura system. The Pelco SDK can discover Endura systems on the network and add that information to the device cache.
 
The sample code discussed in this article is shown here in its entirety. Code snippets will be highlighted in the following sections to illustrate specific device cache functionality. The program is contained in one C++ file. It uses console input to perform device cache actions. Output is displayed on the console. Device cache database snapshots are presented following each action to show the changes that have occurred.
 
// Startup the PelcoSDK
PelcoSDK::Startup();

// Call Pelco SDK functions
try
{
    PelcoSDK::Administrator administrator( PelcoSDK::PString( "admin" ) );

    bool done = false;

    printf( "Press 'e' to create an edge system, 
        'n' to create an Endura system, 
        'l' to list systems, 
        'r' to remove all systems, 
        'q' to quit.\n" );

    while ( done == false )
    {
        int c = getchar();

        if ( c == 'q' )
        {
            done = true;
        }
        else if ( c == 'l' )
        {
            printf( "Listing all systems:\n" );

            PelcoSDK::SystemCollection collection = PelcoSDK::SystemCollection();

            for ( unsigned int index = 0; index < collection.GetCount(); index++ )
            {
                printf( "  %s\n", collection.GetItem( index ).GetDisplayName() );
            }

            printf( "End of system list.\n" );
        }
        else if ( c == 'r' )
        {
            printf( "Removing all systems.\n" );

            administrator.RemoveAllSystems();
        }
        else if ( c == 'e' )
        {
            try
            {
                printf( "Creating edge system.\n" );

                PelcoSDK::System system( PelcoSDK::PString( 
                  "admin:admin@pelcoedgedevices://?alias=SampleSystemEdge" ) );

                system.GetDeviceCollection().Add(
                  "admin:admin@pelcoedgedevices://192.168.5.29" );

                system.GetDeviceCollection().Add(
                  "admin:admin@pelcoedgedevices://192.168.5.104" );
            }
            catch ( PelcoSDK::Exception ex )
            {
                printf( "An error occurred creating the edge system: %s\n", 
                  ex.Message().c_str() );
            }
        }
        else if ( c == 'n' )
        {
            try
            {
                printf( "Creating Endura system.\n" );

                PelcoSDK::System system( PelcoSDK::PString( 
                  "admin:admin@pelcosystem://?alias=SampleSystem" ) );
            }
            catch ( PelcoSDK::Exception ex )
            {
                printf( "An error occurred creating the Endura system: %s\n", 
                  ex.Message().c_str() );
            }
        }
    }
}
catch ( PelcoSDK::Exception ex )
{
    printf( "An error occurred: %s\n", ex.Message().c_str() );
}

// Shutdown the PelcoSDK
PelcoSDK::Shutdown();
 

Initializing the Device Cache

The device cache is created the first time the SDK starts up. If the cache already exists the runtime executes an integrity check and verifies the cache contents against the systems and devices on the network. It then makes the cache available to the running application.
 
// Startup the PelcoSDK
PelcoSDK::Startup();
 
 
Figure 1 shows the contents of the device cache folder after initialization. The PelcoDeviceCache file is the cache database. The path to the device cache folder is visible in the Address Bar.
 
Figure 1. Device cache folder contents.
 
In Figure 2 the System table is empty. However, notice in Figure 3 that the DeviceType table contains static entries for known device types.
 
Figure 2. Initial device cache System table.
 
Figure 3. Device cache DeviceType table.
 

Creating an Edge Device System

Creating an edge device system requires some work because the system must be specified properly using a URL scheme and devices must be added manually (in code). The URL scheme includes credentials, a provider type (required), and an alias. The provider type for an edge device system is pelcoedgedevices. The alias can be any string. No IP address should be specified since this is a virtual system residing only in the local device cache. Details about the scheme components can be found in the SDK Programming Guide.
 
try
{
    printf( "Creating edge system.\n" );

    PelcoSDK::System system( PelcoSDK::PString( 
      "admin:admin@pelcoedgedevices://?alias=SampleSystemEdge" ) );

    system.GetDeviceCollection().Add(
      "admin:admin@pelcoedgedevices://192.168.5.29" );

    system.GetDeviceCollection().Add(
      "admin:admin@pelcoedgedevices://192.168.5.104" );
}
catch ( PelcoSDK::Exception ex )
{
    printf( "An error occurred creating the edge system: %s\n", 
      ex.Message().c_str() );
}
 
 
The device cache System table shown in Figure 4 contains the entry for the newly added edge device system.
 
Figure 4. System table containing an edge system.
 
The Device table shown in Figure 4 contains the entries for the devices added manually. Values in the Type column correspond to the type listed in Figure 3. Two of these entries are cameras, one is an alarm array, and one is a relay array. One of the cameras has associated relays and alarms configured, and so has three entries in the table.
 
Figure 5. Device table for edge system.
 

Creating an Endura System

Creating an Endura system is slightly simpler (in terms of code) than creating an edge device system because the physical system and its devices can be discovered by the SDK. The provider type is pelcosystem. Leaving the IP address value blank causes the SDK to search the network for a System Manager (SM) and automatically add the devices associated with that SM. Figure 6 shows output generated by the SDK during the discovery process.
 
try
{
    printf( "Creating Endura system.\n" );

    PelcoSDK::System system( PelcoSDK::PString( 
      "admin:admin@pelcosystem://?alias=SampleSystem" ) );
}
catch ( PelcoSDK::Exception ex )
{
    printf( "An error occurred creating the edge system: %s\n", 
      ex.Message().c_str() );
}
 
 
Figure 6. Create an Endura system.
 
The discovery process can take some time. Looking at the System table early in the process shows a reservation for the Endura system but the final entry is not in place, as shown in Figure 7.
 
Figure 7. System table with reservation for Endura system.
 
Once device discovery is complete, the Endura system has a complete entry in the System table, as shown in Figure 8.
 
Figure 8. System table with added Endura system.
 
Figure 9 shows the updated Device table. Contrast this with Figure 5, which only contained the edge devices added manually. Four of the entries now have a Ref Count of 2, meaning they are associated with both systems.
 
Figure 9. Device table with added Endura system devices.
 
The device cache file size increases as well, from 14 KB for the empty file to 29 KB for the two system file, as shown in Figure 10.
 
Figure 10. Device cache file has grown.
 
 

Managing Existing Systems

The systems in the cache are accessible through the SystemCollection class. Figure 11 shows the results of iterating over the System objects in the device cache.
 
printf( "Listing all systems:\n" );

PelcoSDK::SystemCollection collection = PelcoSDK::SystemCollection();

for ( int index = 0; index < collection.GetCount(); index++ )
{
    printf( "  %s\n", collection.GetItem( index ).GetDisplayName() );
}

printf( "End of system list.\n" );
 
 
Figure 11. List systems in the device cache.
 
Attempting to add a duplicate Endura system results in a silent failure, but attempting to add a duplicate edge device system results in a more verbose message, as shown in Figure 12.
 
Figure 12. Cannot create duplicate systems.
 
Sometimes it is easier to start over rather than manipulate the existing systems in the device cache. Remove systems from the device cache using the RemoveSystem() or RemoveAllSystems() methods of the Administrator object. Figure 13 shows the console output from RemoveAllSystems().
 
PelcoSDK::Administrator administrator( PelcoSDK::PString( "admin" ) );

printf( "Removing all systems.\n" );

administrator.RemoveAllSystems();
 
 
Figure 13. Remove all systems.
 
The System and Device tables are now empty, as shown in Figures 14 and 15.
 
 
Figure 14. System table after removal.
 
Figure 15. Device table after removal.
 

Change the Device Cache Password

The Administrator can change the password associated with the device cache. The default password is admin but once the Administrator object has been created, the password can be changed using the ChangePasswordTo() method.
 
PelcoSDK::Administrator administrator( PelcoSDK::PString( "admin" ) );

administrator.ChangePasswordTo( newPassword );
 
 
Using the techniques outlined in this article an application can add and remove systems from the device cache.
 

For More Information…

The links below provide additional information regarding the Pelco SDK Object Model and device cache.