Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

AWS

Documentation

Support

My Cases

Console

Vega Developer Docs

Home

Get Started

Design and Develop

Publish

Reference

Support

@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.

Copied to clipboard.

{
    "dependencies": {
        "@amazon-devices/kepler-system-info": "^1.0.2",
        "@amazon-devices/keplerscript-turbomodule-api": "^1.0.0"
    }
}

To install the dependencies run the following command.

Copied to clipboard.

npm install

Usage Examples

Basic usage pattern

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

Copied to clipboard.

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.

Copied to clipboard.

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.

Copied to clipboard.

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.

Copied to clipboard.

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.

Copied to clipboard.

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.

Copied to clipboard.

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
}

Modules

Last updated: Dec 15, 2025