Braiins OS Public API

This repository contains protocol buffers for the new Braiins OS Public API, which is based on gRPC API technology.

Versions

Public API Version	Braiins OS version
1.12.0	26.06
1.11.0	26.05
1.10.0	26.04
1.9.0	26.01
1.8.0	25.11
1.7.0	25.07
1.6.0	25.05
1.5.0	25.03
1.4.0	25.01
1.3.0	24.09
1.2.0	24.06
1.1.0	24.04
1.0.0	24.03
1.0.0-beta.6	24.02
1.0.0-beta.5	23.12
1.0.0-beta.4	23.10.1
1.0.0-beta.3	23.10
1.0.0-beta.2	23.08
1.0.0-beta.1	23.05
1.0.0-beta	23.04
1.0.0-alpha.1	23.03.3
1.0.0-alpha	23.03

Overview

The Braiins OS Public API, introduced in version 23.03, represents a significant milestone in our platform's evolution. This API sets a standard for all present and forthcoming hardware variants, irrespective of their manufacturer. It provides a unified interface for interacting with mining hardware, enabling seamless integration with third-party applications and services. The API is designed to be intuitive, efficient, and versatile, offering a wide range of functionalities to meet diverse requirements.

Examples

We've curated a collection of examples demonstrating the utilization of our Public API, conveniently hosted on our GitHub repository: https://github.com/braiins/bos-plus-api-demos. These examples serve as practical guides for integrating our API into your projects, showcasing its versatility and ease of use. Explore the repository to discover hands-on demonstrations tailored to various use cases.

Getting Started

gRPC is a high-performance remote procedure call (RPC) framework developed by Google. It allows developers to create efficient and reliable communications between client and server applications running on different platforms and written in different programming languages. Read more about gRPC at grpc.io

Prerequisites

• Miner must have port 50051 enabled. As of Braiins OS version 23.03.1, it should be enabled by default.

There is no specific prerequisite for using Braiins OS Public API. It is possible to directly access it using standard GUI tools like Postman, Kreya or CLI tool like grpcurl. Please find an example how to access gRPC api using grpcurl below.

Installation

Read https://github.com/fullstorydev/grpcurl

Usage

Best way to start using our public API is to list available services and describe them. This can be done 2 ways:

• using prepared proto files,
• using reflection.

Proto files

Example of how to list available services in proto file and how to describe service.

$ grpcurl -import-path ./proto -proto bos/v1/actions.proto list
braiins.bos.v1.ActionsService

$ grpcurl -import-path ./proto -proto bos/v1/actions.proto describe
braiins.bos.v1.ActionsService is a service:
service ActionsService {
  // Method to pause mining
  rpc PauseMining ( .braiins.bos.v1.PauseMiningRequest ) returns ( .braiins.bos.v1.PauseMiningResponse );
  // Method to reboot whole miner
  rpc Reboot ( .braiins.bos.v1.RebootRequest ) returns ( .braiins.bos.v1.RebootResponse );
  // Method to restart bosminer
  rpc Restart ( .braiins.bos.v1.RestartRequest ) returns ( .braiins.bos.v1.RestartResponse );
  // Method to resume mining
  rpc ResumeMining ( .braiins.bos.v1.ResumeMiningRequest ) returns ( .braiins.bos.v1.ResumeMiningResponse );
  // Method to start bosminer
  rpc Start ( .braiins.bos.v1.StartRequest ) returns ( .braiins.bos.v1.StartResponse );
  // Method to stop bosminer
  rpc Stop ( .braiins.bos.v1.StopRequest ) returns ( .braiins.bos.v1.StopResponse );
}

Reflection

Braiins OS Public API has gRPC Server Reflection enabled. gRPC Server Reflection provides information about publicly-accessible gRPC services on a server, and assists clients at runtime to construct RPC requests and responses without precompiled service information. It is used by gRPC CLI, which can be used to introspect server protos.

Readme more at gRPC Server Reflection Tutorial.

Examples

List available services

$ grpcurl -plaintext miner:50051 list
braiins.bos.ApiVersionService
braiins.bos.v1.ActionsService
braiins.bos.v1.AdvancedSettingsService
braiins.bos.v1.AuthenticationService
braiins.bos.v1.ConfigurationService
braiins.bos.v1.CoolingService
braiins.bos.v1.MinerService
braiins.bos.v1.PoolService
braiins.bos.v1.TunerService
braiins.bos.v1.UpgradeService
grpc.reflection.v1alpha.ServerReflection

Describe available service

$ grpcurl -plaintext miner:50051 describe
braiins.bos.ApiVersionService is a service:
service ApiVersionService {
  rpc GetApiVersion ( .braiins.bos.ApiVersionRequest ) returns ( .braiins.bos.ApiVersion );
}
braiins.bos.v1.ActionsService is a service:
service ActionsService {
  // Method to pause mining
  rpc PauseMining ( .braiins.bos.v1.PauseMiningRequest ) returns ( .braiins.bos.v1.PauseMiningResponse );
  // Method to reboot whole miner
  rpc Reboot ( .braiins.bos.v1.RebootRequest ) returns ( .braiins.bos.v1.RebootResponse );
  // Method to restart bosminer
  rpc Restart ( .braiins.bos.v1.RestartRequest ) returns ( .braiins.bos.v1.RestartResponse );
  // Method to resume mining
  rpc ResumeMining ( .braiins.bos.v1.ResumeMiningRequest ) returns ( .braiins.bos.v1.ResumeMiningResponse );
  // Method to start bosminer
  rpc Start ( .braiins.bos.v1.StartRequest ) returns ( .braiins.bos.v1.StartResponse );
  // Method to stop bosminer
  rpc Stop ( .braiins.bos.v1.StopRequest ) returns ( .braiins.bos.v1.StopResponse );
  // Method to perform factory reset
  rpc FactoryReset ( .braiins.bos.v1.FactoryResetRequest ) returns ( .braiins.bos.v1.FactoryResetResponse )
}
braiins.bos.v1.AuthenticationService is a service:
service AuthenticationService {
  rpc Login ( .braiins.bos.v1.LoginRequest ) returns ( .braiins.bos.v1.LoginResponse );
}
...

Authentication

The vast majority of requests necessitate authentication, achieved by presenting a token in the Authorization header. This token primarily functions as a session token rather than an authentication token, mirroring the approach in the Braiins OS GUI. Sessions are time-limited, with tokens expiring after 3600 seconds of inactivity. Renewed activity prolongs the session, effectively extending its expiration. Consequently, a session remains active if requests are consistently made within short intervals.

How to get auth token

Send a request with username and password to Login method in AuthenticationService. The token is present in the response body in token field.

$ grpcurl -plaintext -d '{"username": "xxxx", "password": "yyyy"}' miner:50051 braiins.bos.v1.AuthenticationService/Login
{
  "token": "eUInGZBQ4yGyKiDe",
  "timeoutS": 3600
}

Note: Legacy way that token is present in the response header authorization still works.

How to use auth token

To authenticate requests with a token just add authorization header with token using -H flag.

$ grpcurl -plaintext -H 'authorization:FvZarvVQLCtzNaM6' miner:50051 braiins.bos.v1.MinerService/GetMinerDetails
{
  "uid": "lAOJ0RbI6axyOyGf",
  "minerIdentity": {
    "brand": "MINER_BRAND_ANTMINER",
    "model": "MINER_MODEL_ANTMINER_S19J_PRO", // Deprecated, use miner_model
    "name": "Antminer S19J Pro"
    "miner_model": "Antminer S19J Pro",
  },
  "platform": "PLATFORM_AM3_BBB",
  "bosMode": "BOS_MODE_NAND",
  "bosVersion": {
    "current": "2023-04-20-0-0ce150e9-23.03-plus",
    "major": "2022-09-13-0-11012d53-22.08-plus",
    "bosPlus": true
  },
  "hostname": "localhost",
  "macAddress": "94:e3:6d:fb:89:ad",
  "systemUptime": "90919",  // Deprecated, use system_uptime_s
  "bosminer_uptime_s": "5050",
  "system_uptime_s": "90919",
  "status": "MINER_STATUS_NORMAL",
  "kernel_version": "3.8.13+"
}

Version

It is important to note what version of Public API must be used for communication with the miner. Current API version on the miner is available via GetApiVersion method in braiins.bos.ApiVersionService. This service does not require authentication.

$ grpcurl -plaintext miner:50051 braiins.bos.ApiVersionService/GetApiVersion
{
    "major": "1",
    "minor": "3",
    "patch": "0",
    "pre": "",
    "build": ""
}

Note: Version 1.0.0-<ver> is actually 1.0.0-<ver>.0. 0 as default value was dropped during serialization.

Proto files

1. proto/bos/v1/actions.proto

Contains miner actions related protobuf messages and ActionsService with various method to control miner:

• Start - method to start mining,
• Stop - method to stop mining,
• PauseMining - method to pause mining,
• ResumeMining - method to resume mining,
• Restart - method to restart mining,
• Reboot - method to reboot whole miner,
• FactoryReset - method to perform factory reset,
• SetLocateDeviceStatus - method to enable/disable locate device mode,
• GetLocateDeviceStatus - method to retrieve the locate device mode status.

2. proto/bos/v1/authentication.proto

Contains authentication related messages and AuthenticationService with various methods:

• Login - method to log in and get auth. token,
• SetPassword - method to set new password.

3. proto/bos/v1/common.proto

Contains SaveAction enumeration used for setting configuration. Options:

• SAVE_ACTION_SAVE - only save new configuration
• SAVE_ACTION_SAVE_AND_APPLY - save and apply new configuration
• SAVE_ACTION_SAVE_AND_FORCE_APPLY - save and force apply new configuration

4. proto/bos/v1/configuration.proto

Contains configuration related messages and ConfigurationService with various methods to read or modify miner settings:

• GetMinerConfiguration - method to read current miner configuration,
• GetConstraints - method to read current configuration constraints(min, max, default).

5. proto/bos/v1/constraints.proto

Contains protobuf messages used for constraints.

6. proto/bos/v1/cooling.proto

Contains cooling related messages and CoolingService with various methods to read cooling info and modify cooling settings:

• GetCoolingState - method to read current temperature measurements and fans states,
• SetImmersionMode - method to set/toggle immersion mode.

7. proto/bos/v1/license.proto

Contains license related messages and LicenseService with method to read license state:

• GetLicenseState - method to read current license state.

8. proto/bos/v1/miner.proto

Contains miner related messages and MinerService with various methods to read info about miner:

• GetMinerStatus - method to fetch miner status,
• GetMinerDetails - method to read miner details info like model, IP, uptime, etc.,
• GetMinerStats - method to read aggregated miner stats,
• GetErrors - method to get all miner errors,
• GetHashboards - method to read miner hashboards state and statistics,
• GetSupportArchive - method to download Braiins OS support archive,
• GetLog - method to download merged miner log file,
• EnableHashboards - method to enable hashboards,
• DisableHashboards - method to disable hashboards.

9. proto/bos/v1/network.proto

Contains network related messages and NetworkService with various methods to read and modify network settings:

• GetNetworkConfiguration - method to read network configuration,
• SetNetworkConfiguration - method to modify network configuration,
• GetNetworkInfo - method to get current network configuration for the default network interface.

10. proto/bos/v1/performance.proto

Contains tuner related messages and PerformanceService with various methods to read or modify tuner:

• GetTunerState - method to read current tuner state and available tuner profiles,
• ListTargetProfiles - method to set default power target,
• GetMinerEfficiencyProfile - method to get the miner efficiency curve as an array of points ordered by power target,
• SetDefaultPowerTarget - method to set default power target,
• SetPowerTarget - method to set specific power target,
• IncrementPowerTarget - method to increment currently configured power target by a specific value,
• DecrementPowerTarget - method to decrement current configured power target by a specific value,
• SetDefaultHashrateTarget - method to set default hashrate target,
• SetHashrateTarget - method to set specific hashrate target,
• IncrementHashrateTarget - method to increment currently configured hashrate target by a specific value,
• DecrementHashrateTarget - method to decrement current configured hashrate target by a specific value,
• SetDPS - method to set Dynamic Performance Scaling,
• SetPerformanceMode - method to set performance mode,
• GetActivePerformanceMode - method to read active(runtime) performance mode.

11. proto/bos/v1/pool.proto

Contains pools related messages and PoolService with various methods to read or modify pool settings:

• GetPoolGroups - method to read current pools state and statistics,
• CreatePoolGroup - method to create pool group
• UpdatePoolGroup - method to update default pool group,
• RemovePoolGroup - method to remove pool group.
• SetPoolGroups - method to set all pool groups at once.

12. proto/bos/v1/units.proto

Contains protobuf messages representing various units like Voltage, Frequency, etc.

13. proto/bos/v1/upgrade.proto

Contains upgrade related messages and UpgradeService with methods to configure and monitor automatic firmware upgrades, to perform manual firmware upgrade or restore stock firmware:

• UpdateAutoUpgradeConfig - method to enable/disable AutoUpgrade feature and configure upgrade schedule,
• GetAutoUpgradeStatus - method to retrieve current AutoUpgrade configuration and execution status,
• SystemUpgrade - method to perform manual upgrade,
• RestoreStock - method to restore stock firmware.

The AutoUpgrade feature allows the miner to automatically upgrade its firmware according to a configured schedule. You can schedule upgrades to run:

• Daily - at a specific time each day
• Weekly - on a specific day of the week at a specific time
• Monthly - on a specific day of the month (1-28) at a specific time

Notes:

• The dayOfWeek field uses the units.DayOfWeek enum with value for each day in a week.
• The time field uses the UpgradeTime message with fields:
  • hours - hour of day in 24-hour format (0-23)
  • minutes - minutes of hour (0-59)
  • seconds - seconds of minute (0-59, optional, defaults to 0)
• For monthly schedules, dayOfMonth is limited to values 1-28 to ensure compatibility across all months
• When updating the configuration, both enabled and schedule fields are optional - you can update just one or both
• The lastExecution timestamp indicates when the last automatic upgrade was performed (if any)
• The nextExecution timestamp indicates when the next automatic upgrade will occur
• Important: When schedule attributes are not supplied, they will be randomized:
  • For DailySchedule: if time (hours/minutes) is not set, a random time of day will be generated
  • For WeeklySchedule: if dayOfWeek is not set, a random day of the week will be generated; if time is not set, a random time of day will be generated
  • For MonthlySchedule: if dayOfMonth is not set, a random day (1-28) will be generated; if time is not set, a random time of day will be generated

14. proto/bos/v1/work.proto

Contains mining work related protobuf messages.

15. proto/bos/version.proto

Contains ApiVersionService service with GetApiVersion to be able to read current Public API version available for communication with miner

16. proto/bos/v1/advanced_settings.proto

Contains settings related messages and AdvancedSettingsService for managing experimental features and advanced configuration options:

• GetSettings - method to retrieve settings with their current values. By default only user-configured settings are returned; use include_default to include settings with default values,
• SetSettings - method to atomically update one or more settings in a single call; passing a null value clears a setting and restores its default. If any setting fails validation, the whole request is rejected via a standard gRPC error and no settings are changed. On success, the response echoes back the applied settings (null for settings that were cleared),
• GetSettingsSchema - method to retrieve a JSON Schema defining all available settings with their types, constraints, metadata, and default values,
• ResetAllSettings - method to reset all settings to their default values and return the effective values of all supported settings after the reset.

Contact

Do you have questions or specific needs from the API? Our dev and support teams are always available to help. You can send a request to our support team or open a GitHub issue.

You can also join our Telegram group at https://t.me/BraiinsOS point and customize it to fit your project's specific needs.