Hologram API

Hologram's API allows you to access system information and weather data. To access this data you will use Hologram's get method:

Hologram.get(widget, key, callback)

The first parameter must be a reference to your widget. The key is the name of the data being requested. The callback is called automatically every time the data changes. There is no need to call the method more than once. And since we extended the HologramWidget component, the Hologram api will automatically remove the listener when the widget is removed or destroyed.

Here's an example that gets the the computer's CPU usage:

Hologram.get(this, 'cpuUsage', (cpuUsage) => {
    console.log('CPU USAGE', cpuUsage)
})

You'll find a full list of available keys below.

Remove Listener

All data getting methods are automatically removed when a widget is destroyed. However, there are cases where you might want to stop receiving data. For example, if your widget lets users show/hide information, it's a good practice to remove the listener when that particular data isn't being shown to prevent unnecessary usage of the users computer resources.

For example if your widget can optionally show the weather, you should only fetch it if it's being displayed. This can be done by using a vue watcher on the setting, and depending on the value remove or add the listener.

let id = Hologram.get(this, 'weather', (weather) => {
    console.log('get weather', weather)
})

// Stop getting the weather
Hologram.removeListener(this, id)

Weather

See the weather page for more info.

Hologram.get(this, 'currentWeather', (weather) => {
    console.log(weather)
})

Sunrise / Sunset

Returns an object with the sunrise and sunset times in unix time.

Hologram.get(this, 'sunriseSunset', (info) => {
    console.log(info.sunrise, info.sunset)
})

Coordinates

Returns the latitude, longitude, and city name based on the location the user has set as their "weather location" in Hologram's preferences.

Hologram.get(this, 'coordinates', (c) => {
    console.log(c)
})

Returns an object with this prototype:

{
    latitude: 123.000
    longitude: -123.000
    name: "City, State, Country"
}

Computer usage

Returns the amount of time spent on the computer today, in seconds.

Hologram.get(this, 'computerUsageTimeToday', (timeToday) => {
    console.log(timeToday)
})

Returns the amount of time spent on the computer in the last 30 days. Returns an array of objects { date, time }

Hologram.get(this, 'computerUsageTimeLast30', (usageOverTime) => {
    console.log(usageOverTime)
})

Wallpaper

Returns the URL of the current wallpaper.

Hologram.get(this, 'wallpaper', (wallpaperUrl) => {
    console.log('wallpaper changed', wallpaperUrl)
})

Operating System

The following OS data is available.

volumeInfoMain

The amount of free and used disc space in bytes on your main volume.

Hologram.get(this, 'volumeInfoMain', (volInfo) => {
    console.log(volInfo)
})

Returns:

{
    "name": "Macintosh HD",
    "available": 578928075434,
    "capacity": 1000345825280,
    "used": 421417749846
}

volumeInfoAll

The amount of free and used disc space on all volumes.

Hologram.get(this, 'volumeInfoAll', (volInfo) => {
    console.log(volInfo)
})

Returns an array of disk objects:

[
    {
        "name": "Macintosh HD",
        "capacity": 1000345825280,
        "used": 421420383574,
        "available": 578925441706
    },
    {
        "name": "External Drive",
        "available": 1152377898176,
        "capacity": 2048064274432,
        "used": 895686376256
    }
]

username

Returns a string containing the logon name of the current user.

Hologram.get(this, 'volumeInfoAll', (volInfo) => {
    console.log(volInfo)
})

fullUsername

Returns a string containing the full name of the current user.

Hologram.get(this, 'fullUsername', (un) => {
    console.log(un)
})

hostName

Returns a string containing the computer's hostname.

Hologram.get(this, 'hostName', (hn) => {
    console.log(hn)
})

osVersionNumber

Returns the version number of Mac OS, such as 10.15.3

Hologram.get(this, 'osVersionNumber', (vn) => {
    console.log(vn)
})

osVersionName

Returns name of the OS version, such as Catalina

Hologram.get(this, 'osVersionName', (verName) => {
    console.log(verName)
})

modelName

Returns the model name of the machine. The result is the same as running "sysctl hw.model" in the terminal.

Hologram.get(this, 'modelName', (modelName) => {
    console.log(modelName)
    // Returns model, such as MacBookPro16,1
})

uptime

Returns computer uptime in seconds

Hologram.get(this, 'uptime', (uptime) => {
    console.log(uptime)
})

physicalMemory

The amount of physical memory on the computer in bytes.

Hologram.get(this, 'physicalMemory', (memory) => {
    console.log(memory)
})

processorCount

Returns a string containing the number of processors on the computer.

Hologram.get(this, 'processorCount', (processorCount) => {
    console.log(processorCount)
})

cpuUsage

Returns an object of usage components in percentages

Hologram.get(this, 'cpuUsage', (cpuUsage) => {
    console.log(cpuUsage)
})

Returns:

{
    "system": 5.498333838230839,
    "user": 8.482278097546198,
    "idle": 86.01938806422297
}

memoryUsage

Returns an object of the memory usage components in bytes

Hologram.get(this, 'memoryUsage', (memoryUsage) => {
    console.log(memoryUsage)
})

Returns:

{
    "free": 14188654592,
    "compressed": 977952768,
    "wired": 5798809600,
    "active": 13391212544
}

processCount

Returns an object containing the number of active processes and threads on the computer.

Hologram.get(this, 'processCount', (processCount) => {
    console.log(processCount)
})

Returns:

{
    "threadCount": 5264,
    "processCount": 784
}

battery

Returns an object with battery usage information.

Hologram.get(this, 'battery', battery => {
    this.battery = battery
})

Returns:

{
    "isCharging": false,
    "hasBattery": false,
    "percentage": 100,
    // Time until changed (in minutes) is zero unless the computer is charging
    // It also may be zero if the computer is still calculating
    "timeUntilCharged": 0,
    // Time remaining (in minutes) only appears when the computer is using battery power
    // It also may be zero if the computer is still calculating
    "timeRemaining": 0
}

Note: To convert timeRemaining into hours and minutes use:

Hologram.util.humanizeSeconds(this.battery.timeRemaining * 60)

Public IP Address

Returns the user's public IP.

Hologram.get(this, 'publicIP', ip => {
    console.log(ip)
})