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

/ping

Sample request:

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

Default response:

Status: 200 OK

pong

Get list of valid endpoints

/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

/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

/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

/routines

Sample request

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

Default response

Status: 204 No Content

Restart routine

/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

/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

/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

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