Skip to content

snhilde/statusbar

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 

Repository files navigation

Maintenance Badge PkgGoDev Doc GoReportCard Build Status

statusbar

statusbar formats and displays information on the dwm statusbar.

You can find the current release here: https://github.com/snhilde/statusbar/tree/master/v5.

Table of Contents

  1. Overview
  2. Installation
  3. Usage and Documentation
  4. Modules
  5. REST API
    1. Version 1
      1. Path prefix
      2. Ping the system
      3. Get list of valid endpoints
      4. Get information about all routines
      5. Get information about routine
      6. Restart all routines
      7. Restart routine
      8. Modify routine's settings
      9. Stop all routines
      10. Stop routine
  6. Contributing

Overview

statusbar is an engine for handling the various components that make up the statusbar. The components are modular routines that handle their own logic for gathering and formatting data, with each routine run in its own thread. The engine triggers the routines to run their update process according to the time interval set by the caller and gathers the individual pieces of data for printing on the statusbar.

Integrating a custom module is very simple. See Modules for more information.

Installation

statusbar is a package, not a stand-alone program. To download the package, you can use gotools in this way:

go get github.com/snhilde/statusbar

That will also pull in the repository's modules for quick activation.

Usage and Documentation

To get up and running with this package, follow these steps:

  1. Create a new statusbar object.
  2. Add routines to the statusbar.
  3. Run the engine.

You can find the complete documentation and usage guidelines at pkg.go.dev. The docs also include an example detailing the steps above.

Modules

statusbar is modular by design, and it's simple to build and integrate modules; you only have to implement a few methods.

This repository includes these modules to get up and running quickly:

Module Documentation Major usage
sbbattery PkgGoDev Doc Battery usage
sbcputemp PkgGoDev Doc CPU temperature
sbcpuusage PkgGoDev Doc CPU usage
sbdisk PkgGoDev Doc Filesystem usage
sbfan PkgGoDev Doc Fan speed
sbgithubclones PkgGoDev Doc Github repo clone count
sbload PkgGoDev Doc System load averages
sbnetwork PkgGoDev Doc Network usage
sbnordvpn PkgGoDev Doc NordVPN status
sbram PkgGoDev Doc RAM usage
sbtime PkgGoDev Doc Current date/time
sbtodo PkgGoDev Doc TODO list display
sbtravisci PkgGoDev Doc Travis CI build status
sbvolume PkgGoDev Doc Volume percentage
sbweather PkgGoDev Doc Weather information

REST API

statusbar comes packaged with a REST API. This API (and all future APIs) is disabled by default. To activate it, you need to call EnableRESTAPI with the port you want the microservice to listen on before running the main Statusbar engine.

The REST API makes use of the wonderful Gin framework. For details on adding/modifying endpoints, see the documentation in the restapi package.

Version 1

Path prefix

/rest/v1

Ping the system

GET Badge /ping

Sample request:

curl -X GET http://localhost:1234/rest/v1/ping

Default response:

Status: 200 OK
pong

Get list of valid endpoints

GET Badge /endpoints

Sample request:

curl -X GET http://localhost:1234/rest/v1/endpoints

Default response:

Status: 200 OK
{
	"endpoints": [
		{
			"method": "GET",
			"url": "/ping",
			"description": "Ping the system."
		},
		{
			"method": "GET",
			"url": "/endpoints",
			"description": "Get a list of valid endpoints."
		},
		...
	]
}

Internal error:

Status: 500 Internal Server Error
{
	"error": "error message"
}

Get information about all routines

GET Badge /routines

Sample request:

curl -X GET http://localhost:1234/rest/v1/routines

Default response:

Status: 200 OK
{
	"routines": {
		"sbbattery": {
			"name": "Battery",
			"uptime": 35212,
			"interval": 30,
			"active": true
		},
		"sbcputemp": {
			"name": "CPU Temp",
			"uptime": 35212,
			"interval": 1,
			"active": true
		},
		...
	}
}

Get information about routine

GET Badge /routines/{routine}

Parameters Location Description
routine path Routine's module name

Sample request

curl -X GET http://localhost:1234/rest/v1/routines/sbfan

Default response

Status: 200 OK
{
	"sbfan": {
		"name": "Fan",
		"uptime": 242,
		"interval": 1,
		"active": true
	}
}

Bad request

Status: 400 Bad Request
{
	"error": "invalid routine"
}

Restart all routines

PUT Badge /routines

Sample request

curl -X PUT http://localhost:1234/rest/v1/routines

Default response

Status: 204 No Content

Restart routine

PUT Badge /routines/{routine}

Parameters Location Description
routine path Routine's module name

Sample request

curl -X PUT http://localhost:1234/rest/v1/routines/sbweather

Default response

Status: 204 No Content

Bad request

Status: 400 Bad Request
{
	"error": "invalid routine"
}

Modify routine's settings

PATCH Badge /routines/{routine}

Parameters Location Description
routine path Routine's module name
interval body New interval time, in seconds

Sample request

curl -X PATCH --data '{"interval": 5}' http://localhost:1234/rest/v1/routines/sbcputemp

Default response

Status: 202 Accepted

Bad request

Status: 400 Bad Request
{
	"error": "error message"
}

Stop all routines

DELETE Badge /routines

Sample request

curl -X DELETE http://localhost:1234/rest/v1/routines

Default response

Status: 204 No Content

Internal error:

Status: 500 Internal Server Error
{
	"error": "failure"
}

Stop routine

DELETE Badge /routines/{routine}

Parameters Location Description
routine path Routine's module name

Sample request

curl -X DELETE http://localhost:1234/rest/v1/routines/sbgithubclones

Default response

Status: 204 No Content

Bad request

Status: 400 Bad Request
{
	"error": "invalid routine"
}

Internal error:

Status: 500 Internal Server Error
{
	"error": "failure"
}

Contributing

If you find a bug, please submit a pull request. If you think there could be an improvement, please open an issue or submit a pull request with the recommended change. Contributions and new modules are always welcome.