This repository contains protocol buffers for the new Braiins OS+ Public API, which is based on gRPC API technology.
| Public API Version | BOS+ version |
|---|---|
| 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 |
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.
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.
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
There is no specific prerequisite for using BOS+ 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.
Read https://github.com/fullstorydev/grpcurl
Best way to start using our public API is to list available services and describe them. This can be done 2 ways:
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
BOS+ 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](https://grpc.github.io/grpc/core/md_doc_server_reflection_tutorial.html)**.
#### Examples
List available services
```shell
$ grpcurl -plaintext miner:50051 list
braiins.bos.ApiVersionService
braiins.bos.v1.ActionsService
braiins.bos.v1.AuthenticationService
braiins.bos.v1.ConfigurationService
braiins.bos.v1.CoolingService
braiins.bos.v1.MinerService
braiins.bos.v1.PoolService
braiins.bos.v1.TunerService
grpc.reflection.v1alpha.ServerReflectionDescribe 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 );
}
braiins.bos.v1.AuthenticationService is a service:
service AuthenticationService {
rpc Login ( .braiins.bos.v1.LoginRequest ) returns ( .braiins.bos.v1.LoginResponse );
}
...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.
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.
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",
"name": "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": "bosminer",
"macAddress": "94:e3:6d:fb:89:ad",
"systemUptime": "90919"
}
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",
"pre": "alpha"
}Note: Version 1.0.0-<ver> is actually 1.0.0-<ver>.0. 0 as default value was dropped during serialization.
Contains miner actions related protobuf messages and ActionsService with various method to control miner:
Contains authentication related messages and AuthenticationService with various methods:
Contains SaveAction enumeration used for setting configuration. Options:
SAVE_ACTION_SAVE - only save new configurationSAVE_ACTION_SAVE_AND_APPLY - save and apply new configurationSAVE_ACTION_SAVE_AND_FORCE_APPLY - save and force apply new configurationContains configuration related messages and ConfigurationService with various methods to read or modify miner settings:
Contains protobuf messages used for constraints.
Contains cooling related messages and CoolingService with various methods to read cooling info and modify cooling settings:
Contains license related messages and LicenseService with method to read license state:
Contains miner related messages and MinerService with various methods to read info about miner:
Contains network related messages and NetworkService with various methods to read and modify network settings:
Contains tuner related messages and PerformanceService with various methods to read or modify tuner:
Contains pools related messages and PoolService with various methods to read or modify pool settings:
Contains protobuf messages representing various units like Voltage, Frequency, etc.
Contains mining work related protobuf messages.
Contains ApiVersionService service with GetApiVersion to be able to read current Public API version available for communication with miner
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.