@amazon-devices/kepler-system-info

The Vega System Info API provides functionality that allows you to query essential system-level information about the running operating system instance. This includes system uptime, operating system details, build information, and hardware characteristics specifically designed for apps running on Vega. The API provides the following key features:

System Uptime Monitoring: Gets precise system uptime with nanosecond accuracy
Operating System Information: Provides access to the OS display name, version, and codename
Build Information: Retrieves detailed build metadata and fingerprints
Emulator Detection: Identifies whether the app is running on the Vega Virtual Device (VVD)
TypeScript Support: The API fully supports TypeScript definition
Error Handling: Supports comprehensive error handling with try-catch patterns

Remarks

The core interfaces for the API are as follows.

Interface	Description
`ISystemInfo`	Main system information interface
`IOperatingSystemInfo`	Operating system details
`IBuildInfo`	Build and version information

The key type definitions are as follows.

Type	Description
`MonotonicDuration`	System uptime duration
`RealTimeInstant`	Timestamp with nanosecond precision
`RawTimeValue`	Raw time value (seconds + nanoseconds)

Getting Started

Setup

Add the following library dependencies to your package.json file.

{
    "dependencies": {
        "@amazon-devices/kepler-system-info": "~1.0.5",
        "@amazon-devices/keplerscript-turbomodule-api": "~1.2.5"
    }
}

To install the dependencies run the following command.

npm install

Usage Examples

Basic usage pattern

The following code example shows the minimal usage of the API.

import { SystemInfoModule, ISystemInfo } from '@amazon-devices/kepler-system-info';

// Get the main SystemInfo interface
let systemInfo: ISystemInfo;
try {
    systemInfo = SystemInfoModule.getSystemInfo();
    console.log('SystemInfo initialized successfully');
} catch (error) {
    console.error('Failed to initialize SystemInfo:', error);
    throw error;
}

ISystemInfo Interface

System Uptime

The following code example shows how to get the system uptime with nanosecond accuracy.

import { MonotonicDuration, RawTimeValue } from '@amazon-devices/kepler-system-info';

async function getSystemUptime() {
    try {
        const uptime: MonotonicDuration = await systemInfo.getUptime();
        const timeValue: RawTimeValue = uptime.time;

        console.log('System Uptime:');
        console.log(`Seconds: ${timeValue.seconds}`);
        console.log(`Nanoseconds: ${timeValue.nanoseconds}`);

        // Convert to human-readable format
        const totalSeconds = timeValue.seconds;
        const hours = Math.floor(totalSeconds / 3600);
        const minutes = Math.floor((totalSeconds % 3600) / 60);
        const seconds = totalSeconds % 60;

        console.log(`Human readable: ${hours}h ${minutes}m ${seconds}s`);

        return uptime;
    } catch (error) {
        console.error('Failed to get system uptime:', error);
        throw error;
    }
}

Emulator detection

The following example code shows how check whether the app is running on the VVD.

function checkEmulatorStatus() {
    try {
        const isEmulator = systemInfo.isEmulator();
        console.log(`Running in emulator: ${isEmulator ? 'Yes' : 'No'}`);

        if (isEmulator) {
            console.log('Development/Testing environment detected');
        } else {
            console.log('Production environment detected');
        }

        return isEmulator;
    } catch (error) {
        console.error('Failed to check emulator status:', error);
        throw error;
    }
}

Access operating system information

The following example code shows how to use the IOperatingSystemInfo interface to access detailed operating system information.

import { IOperatingSystemInfo } from '@amazon-devices/kepler-system-info';

function getOperatingSystemInfo() {
    try {
        const osInfo: IOperatingSystemInfo =
            systemInfo.getOperatingSystemInfo();

        // Get OS details
        const displayName = osInfo.getDisplayName();
        const codeName = osInfo.getCodeName();
        const version = osInfo.getVersion();

        console.log('Operating System Information:');
        console.log(`Display Name: ${displayName}`);
        console.log(`Code Name: ${codeName}`);
        console.log(`Version: ${version}`);

        return {
            displayName,
            codeName,
            version,
            osInfo,
        };
    } catch (error) {
        console.error('Failed to get OS information:', error);
        throw error;
    }
}

Retrieve build information

The following example code shows how to use the IBuildInfo interface to retrieve comprehensive build information.

import {
    IBuildInfo,
    RealTimeInstant,
    RawTimeValue,
} from '@amazon-devices/kepler-system-info';

function getBuildInformation(osInfo: IOperatingSystemInfo) {
    try {
        const buildInfo: IBuildInfo = osInfo.getBuildInfo();

        // Basic build information
        const displayName = buildInfo.getDisplayName();
        const buildId = buildInfo.getId();
        const variant = buildInfo.getVariant();
        const fingerprint = buildInfo.getFingerprint();

        // Build timestamp
        const timestamp: RealTimeInstant = buildInfo.getTimestamp();
        const timeValue: RawTimeValue = timestamp.time;
        const buildDate = new Date(timeValue.seconds * 1000);

        // Build tags
        const tags: string[] = buildInfo.getTags();

        console.log('Build Information:');
        console.log(`Display Name: ${displayName}`);
        console.log(`Build ID: ${buildId}`);
        console.log(`Variant: ${variant}`);
        console.log(`Fingerprint: ${fingerprint}`);
        console.log(`Build Date: ${buildDate.toISOString()}`);
        console.log(`Tags: ${JSON.stringify(tags, null, 2)}`);

        return {
            displayName,
            buildId,
            variant,
            fingerprint,
            buildDate,
            tags,
            buildInfo,
        };
    } catch (error) {
        console.error('Failed to get build information:', error);
        throw error;
    }
}

Example

The following example code demonstrates all major features of the API.

import {
    SystemInfoModule,
    ISystemInfo,
    IOperatingSystemInfo,
    IBuildInfo,
    MonotonicDuration,
    RealTimeInstant,
    RawTimeValue,
} from '@amazon-devices/kepler-system-info';

class SystemInfoService {
    private systemInfo: ISystemInfo;

    constructor() {
        try {
            this.systemInfo = SystemInfoModule.getSystemInfo();
            console.log('SystemInfoService initialized');
        } catch (error) {
            console.error('Failed to initialize SystemInfoService:', error);
            throw error;
        }
    }

    async getCompleteSystemInfo() {
        try {
            // System-level information
            const uptime = await this.systemInfo.getUptime();
            const isEmulator = this.systemInfo.isEmulator();

            // Operating system information
            const osInfo = this.systemInfo.getOperatingSystemInfo();
            const osDisplayName = osInfo.getDisplayName();
            const osCodeName = osInfo.getCodeName();
            const osVersion = osInfo.getVersion();

            // Build information
            const buildInfo = osInfo.getBuildInfo();
            const buildDisplayName = buildInfo.getDisplayName();
            const buildId = buildInfo.getId();
            const buildVariant = buildInfo.getVariant();
            const buildFingerprint = buildInfo.getFingerprint();
            const buildTimestamp = buildInfo.getTimestamp();
            const buildTags = buildInfo.getTags();

            return {
                system: {
                    uptime: {
                        seconds: uptime.time.seconds,
                        nanoseconds: uptime.time.nanoseconds,
                        humanReadable: this.formatUptime(uptime.time.seconds),
                    },
                    isEmulator,
                },
                operatingSystem: {
                    displayName: osDisplayName,
                    codeName: osCodeName,
                    version: osVersion,
                },
                build: {
                    displayName: buildDisplayName,
                    id: buildId,
                    variant: buildVariant,
                    fingerprint: buildFingerprint,
                    timestamp: {
                        seconds: buildTimestamp.time.seconds,
                        nanoseconds: buildTimestamp.time.nanoseconds,
                        date: new Date(
                            buildTimestamp.time.seconds * 1000,
                        ).toISOString(),
                    },
                    tags: buildTags,
                },
            };
        } catch (error) {
            console.error('Failed to get complete system info:', error);
            throw error;
        }
    }

    private formatUptime(seconds: number): string {
        const hours = Math.floor(seconds / 3600);
        const minutes = Math.floor((seconds % 3600) / 60);
        const secs = seconds % 60;
        return `${hours}h ${minutes}m ${secs}s`;
    }
}

// Usage
async function main() {
    try {
        const service = new SystemInfoService();
        const systemInfo = await service.getCompleteSystemInfo();

        console.log('Complete System Information:');
        console.log(JSON.stringify(systemInfo, null, 2));
    } catch (error) {
        console.error('Application error:', error);
    }
}

main();

Error Handling

The API uses standard JavaScript error handling. Always wrap API calls in try-catch blocks.

try {
    const systemInfo = SystemInfoModule.getSystemInfo();
    const uptime = await systemInfo.getUptime();
    // Process uptime...
} catch (error) {
    if (error instanceof Error) {
        console.error(`SystemInfo Error: ${error.message}`);
        console.error(`Stack trace: ${error.stack}`);
    } else {
        console.error('Unknown error occurred:', error);
    }

    // Handle error appropriately for your application
    throw error; // Re-throw if needed
}

API Reference

Core Interfaces

Interface	Description
`ISystemInfo`	Main system information interface
`IOperatingSystemInfo`	Operating system details
`IBuildInfo`	Build and version information

Type Definitions

Type	Description
`MonotonicDuration`	System uptime duration
`RealTimeInstant`	Timestamp with nanosecond precision
`RawTimeValue`	Raw time value (seconds + nanoseconds)

Usage Examples

Basic Setup

import { SystemInfoModule, ISystemInfo } from '@amazon-devices/kepler-system-info';

try {
    const systemInfo = SystemInfoModule.getSystemInfo();
    console.log('SystemInfo initialized successfully');
} catch (error) {
    console.error('Failed to initialize SystemInfo:', error);
    throw error;
}

ISystemInfo Interface

System Uptime

Get precise system uptime with nanosecond accuracy:

import { MonotonicDuration, RawTimeValue } from '@amazon-devices/kepler-system-info';

async function getSystemUptime() {
    try {
        const uptime: MonotonicDuration = await systemInfo.getUptime();
        const timeValue: RawTimeValue = uptime.time;
        
        console.log('System Uptime:');
        console.log(`Seconds: ${timeValue.seconds}`);
        console.log(`Nanoseconds: ${timeValue.nanoseconds}`);
        
        // Convert to human-readable format
        const totalSeconds = timeValue.seconds;
        const hours = Math.floor(totalSeconds / 3600);
        const minutes = Math.floor((totalSeconds % 3600) / 60);
        const seconds = totalSeconds % 60;
        
        console.log(`Human readable: ${hours}h ${minutes}m ${seconds}s`);
        
        return uptime;
    } catch (error) {
        console.error('Failed to get system uptime:', error);
        throw error;
    }
}

Emulator Detection

Check if the application is running in an emulator environment:

function checkEmulatorStatus() {
    try {
        const isEmulator = systemInfo.isEmulator();
        console.log(`Running in emulator: ${isEmulator ? 'Yes' : 'No'}`);
        
        if (isEmulator) {
            console.log('Development/Testing environment detected');
        } else {
            console.log('Production environment detected');
        }
        
        return isEmulator;
    } catch (error) {
        console.error('Failed to check emulator status:', error);
        throw error;
    }
}

IOperatingSystemInfo Interface

Access detailed operating system information:

import { IOperatingSystemInfo } from '@amazon-devices/kepler-system-info';

function getOperatingSystemInfo() {
    try {
        const osInfo: IOperatingSystemInfo = systemInfo.getOperatingSystemInfo();
        
        // Get OS details
        const displayName = osInfo.getDisplayName();
        const codeName = osInfo.getCodeName();
        const version = osInfo.getVersion();
        
        console.log('Operating System Information:');
        console.log(`Display Name: ${displayName}`);
        console.log(`Code Name: ${codeName}`);
        console.log(`Version: ${version}`);
        
        return {
            displayName,
            codeName,
            version,
            osInfo
        };
    } catch (error) {
        console.error('Failed to get OS information:', error);
        throw error;
    }
}

IBuildInfo Interface

Retrieve comprehensive build information:

import { IBuildInfo, RealTimeInstant, RawTimeValue } from '@amazon-devices/kepler-system-info';

function getBuildInformation(osInfo: IOperatingSystemInfo) {
    try {
        const buildInfo: IBuildInfo = osInfo.getBuildInfo();
        
        // Basic build information
        const displayName = buildInfo.getDisplayName();
        const buildId = buildInfo.getId();
        const variant = buildInfo.getVariant();
        const fingerprint = buildInfo.getFingerprint();
        
        // Build timestamp
        const timestamp: RealTimeInstant = buildInfo.getTimestamp();
        const timeValue: RawTimeValue = timestamp.time;
        const buildDate = new Date(timeValue.seconds * 1000);
        
        // Build tags
        const tags: string[] = buildInfo.getTags();
        
        console.log('Build Information:');
        console.log(`Display Name: ${displayName}`);
        console.log(`Build ID: ${buildId}`);
        console.log(`Variant: ${variant}`);
        console.log(`Fingerprint: ${fingerprint}`);
        console.log(`Build Date: ${buildDate.toISOString()}`);
        console.log(`Tags: ${JSON.stringify(tags, null, 2)}`);
        
        return {
            displayName,
            buildId,
            variant,
            fingerprint,
            buildDate,
            tags,
            buildInfo
        };
    } catch (error) {
        console.error('Failed to get build information:', error);
        throw error;
    }
}

API Reference

Classes

MonotonicDuration — Represents a span of time. This type follows ISO 8601 Duration definition.
RawTimeValue — A basic type used to describe both absolute and relative time.
RealTimeInstant — Represents a point in time in the system’s clock. Useful for
SystemInfo
SystemInfoModule — System Information APIs

Interfaces

IBuildInfo — Operating system build-specific information.
IOperatingSystemInfo — Operating System information.
ISystemInfo — Core interface for querying system information.

​Remarks

​Getting Started

​Setup

​Usage Examples

​Basic usage pattern

​ISystemInfo Interface

​System Uptime

​Emulator detection

​Access operating system information

​Retrieve build information

​Example

​Error Handling

​API Reference

​Core Interfaces

​Type Definitions

​Usage Examples

​Basic Setup

​ISystemInfo Interface

​System Uptime

​Emulator Detection

​IOperatingSystemInfo Interface

​IBuildInfo Interface

​API Reference

​Classes

​Interfaces

Remarks

Getting Started

Setup

Usage Examples

Basic usage pattern

ISystemInfo Interface

System Uptime

Emulator detection

Access operating system information

Retrieve build information

Example

Error Handling

API Reference

Core Interfaces

Type Definitions

Usage Examples

Basic Setup

ISystemInfo Interface

System Uptime

Emulator Detection

IOperatingSystemInfo Interface

IBuildInfo Interface

API Reference

Classes

Interfaces