Official Arduino CLI and library. Can run standalone, or be incorporated into larger Go projects.

# arduino-cli

![cli-logo](./docs/img/CLI_Logo_small.png)

Arduino CLI is an all-in-one solution that provides Boards/Library Managers, sketch builder, board detection, uploader,
and many other tools needed to use any Arduino compatible board and platform from command line or machine interfaces.

[![Test Go status](https://github.com/arduino/arduino-cli/actions/workflows/test-go-task.yml/badge.svg)](https://github.com/arduino/arduino-cli/actions/workflows/test-go-task.yml)
[![Publish Nightly Build status](https://github.com/arduino/arduino-cli/actions/workflows/publish-go-nightly-task.yml/badge.svg)](https://github.com/arduino/arduino-cli/actions/workflows/publish-go-nightly-task.yml)
[![Deploy Website status](https://github.com/arduino/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml/badge.svg)](https://github.com/arduino/arduino-cli/actions/workflows/deploy-cobra-mkdocs-versioned-poetry.yml)
[![Codecov](https://codecov.io/gh/arduino/arduino-cli/branch/master/graph/badge.svg)](https://codecov.io/gh/arduino/arduino-cli)

## Docs

For guidance on installation and development, see the [User documentation].

## Quickstart

1. [Install] the Arduino CLI
1. Follow the [Getting Started] guide to check out what the CLI can do
1. Browse the [Commands reference] to see all the available commands
1. Should you have an issue, read the [FAQ] page

## How to contribute

Contributions are welcome!

Please read the document [How to contribute] which will show you how to build the source code, run the tests, and
contribute your changes to the project.

:sparkles: Thanks to all our [contributors]! :sparkles:

### Testing builds

[Nightly builds] are available for testing.

## Security

If you think you found a vulnerability or other security-related bug in the Arduino CLI, please read our [security
policy] and report the bug to our Security Team 🛡️ Thank you!

e-mail contact: security@arduino.cc

## License

Arduino CLI is licensed under the [GPL 3.0] license.

You can be released from the requirements of the above license by purchasing a commercial license. Buying such a license
is mandatory if you want to modify or otherwise use the software for commercial activities involving the Arduino
software without disclosing the source code of your own applications. To purchase a commercial license, send an email to
license@arduino.cc

[install]: https://arduino.github.io/arduino-cli/latest/installation
[user documentation]: https://arduino.github.io/arduino-cli/latest/
[getting started]: https://arduino.github.io/arduino-cli/latest/getting-started/
[commands reference]: https://arduino.github.io/arduino-cli/latest/commands/arduino-cli
[faq]: https://arduino.github.io/arduino-cli/latest/FAQ/
[how to contribute]: https://arduino.github.io/arduino-cli/latest/CONTRIBUTING/
[contributors]: https://github.com/arduino/arduino-cli/graphs/contributors
[nightly builds]: https://arduino.github.io/arduino-cli/latest/installation/#nightly-builds
[security policy]: https://github.com/arduino/arduino-cli/security/policy
[gpl 3.0]: https://www.gnu.org/licenses/gpl-3.0.en.html


arduino-cli

Go-like language for programming embedded systems (e.g. STM32 MCU).

### Emgo

Emgo consist of a compiler and the set of packages that allows you to run Go programs
on small 32-bit microcontrollers. The compiler generates C as an intermediate code
and uses C compiler to produce loadable binaries.

There is [Embedded Go](https://github.com/embeddedgo) project that evolved from
Emgo which is based on the [reference Go compiler](https://golang.org). It has
much higher hardware requirements but it is also 100% compatible with the [Go
language specification](https://golang.org/ref/spec). The main development
process has moved to Embeadded Go but I still use Emgo for small MCUs so some
things can be backported here.

### How to start

First of all, to try Emgo you need the [Go compiler](https://golang.org/) installed. The current Emgo compiler and whole process described below requires also some kind of Unix-like operating system. There is a chance that Windows with Cygwin can be used but this was not tested.

You can probably use `go get` to install Emgo but the preferred way is to clone this repository using the git command:

	git clone https://github.com/ziutek/emgo.git

Next you need to build and install egc (Emgo compiler): 

    cd emgo/egc
    go install

For now, Emgo supports only ARM Cortex-M based MCUs. To build code for Cortex-M architecture, you need to install ARM embedded toolchain. You have two options: install a package included in your OS distribution (in case of Debian/Ubuntu Linux):

	apt-get install gcc-arm-none-eabi

or better go to the [GNU ARM Embedded Toolchain website](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm) and download most recent toolchain. This is preferred version of toolchain, try use it before report any bug with compilation.

Installed toolchain contains set of arm-none-eabi-* binaries. Find their location and set required enviroment variables:

	export EGCC=path_to_arm_gcc            # eg. /usr/local/arm/bin/arm-none-eabi-gcc
	export EGLD=path_to_arm_linker         # eg. /usr/local/arm/bin/arm-none-eabi-ld
	export EGAR=path_to_arm_archiver       # eg. /usr/local/arm/bin/arm-none-eabi-ar

	export EGROOT=path_to_egroot_directory # eg. $HOME/emgo/egroot
	export EGPATH=path_to_egpath_directory # eg. $HOME/emgo/egpath

Load/debug helper scripts use also some other tools from the ARM toolchain (eg. arm-none-eabi-objcopy). If you downloaded the toolchain manually, you probably need also to add its bin directory to the PATH enviroment variable:

	export PATH=$PATH:path_to_arm_bin_dir  # eg. /usr/local/arm/bin

Now you are ready to compile some example code. There are two directories that contain examples:

[$EGPATH/src/stm32/examples](https://github.com/ziutek/emgo/tree/master/egpath/src/stm32/examples)

[$EGPATH/src/nrf5/examples](https://github.com/ziutek/emgo/tree/master/egpath/src/nrf5/examples)

Use one that contains example for your MCU/devboard.

For example, to build blinky for STM32 NUCLEO-F411RE board:

	cd $EGPATH/src/stm32/examples/nucleo-f411re/blinky
    ../build.sh

The first compilation may take some time because egc must process all required libraries and runtime. If everything went well you obtain cortexm4f.elf binary file.

Compilation can produce two kind of binaries: binaries that should be loaded to RAM or loaded to Flash of your MCU.

Loading to RAM is useful in case of small programs, during working on the code and debuging. Loading to RAM is faster, allows unlimited number of breakpoints, allows to modify constants and even the code from debuger and saves your Flash, which has big but limited number of erase cycles.

To run program loaded to RAM you must change the MCU boot behavior. In case of most STM32 MCUs you simply need to set high BOOT0 and BOOT1 pins. Newer STM32 MCUs do not provide BOOT1 pin, insdead they require to program some persistant bits that change the default booting behavior when BOOT0 is set high.

However, eventually your program should be loaded to Flash. Sometimes you have no other alternative: your program is too big to fit into RAM or your MCU does not provide easy way to run program from RAM (eg. nRF51). Some bugs may only appear when the program runs from Flash or from RAM, so it is advisable to perform the final test of any new piece of code in both ways.

You need tools to load compiled binary to your MCU's RAM/Flash and allow to debug it. Such tools usually have a hardware part and a software part. In case of STM32 Nucleo or Discovery development boards the hardware part (ST-LINK programmer) is integrated with the board, so you only need the software part, which can be [OpenOCD](http://openocd.org) or [Texane's stlink](https://github.com/texane/stlink). You must install one of them or both before next steps (ensure that openocd and/or st-util binaries are on your PATH). 

There is a set of scripts for any board in example directory that simplifies loding and debuging process. The load-oocd.sh and swo-oocd.sh scripts can handle SWO output from ITM (Instrumentation Trace Macrocell) but needs [itmsplit](https://github.com/ziutek/itmsplit) to convert binary stream to readable messages. SWO is very useful for debuging and `fmt.Print*` functions by default use ITM trace port as standard output. Install itmsplit with the command:

	go get github.com/ziutek/itmsplit
	
and ensure that produced binary is in your PATH.

You need the rights to the USB device that corresponds to your programming hardware. This can be done through adding appropriate udev rules. See example rules in Texane's stlink repository, in etc directory.

To program your MCU using Texane's stlink run:

	../load-stutil.sh

If you want to use OpenOCD, run:

	../load-oocd.sh

Some examples by default are configured to run from RAM. If you have problem to setup your board to run from RAM, edit script.ld file and change the line:

	INCLUDE stm32/loadram

to

	INCLUDE stm32/loadflash

More editing is need for STM32F1xx series: you additionally have to comment two lines:

	bootOffset = 0x1E0;
	ENTRY(bootRAM)

You can also load your program during debug session in gdb. Run `../debug-stutil.sh` or `../debug-oocd.sh` and next invoke `load` command.

There are also scripts for [Black Magic Probe](https://github.com/blacksphere/blackmagic/wiki): load-bmp.sh, debug-bmp.sh.

If you played with examples and enjoyed Emgo you probably want to write your first program from scratch, compile it and load without all these magical scripts. This [blog post](https://ziutek.github.io/2018/03/30/go_on_very_small_hardware.html) presents how to do it.

You may encounter a problem where st-util or openocd can not connect to your board. This is often the case for boards without integrated programmer/debuger, when the external programmer has no connection to the reset pin. If you can not make such connection, simply press and hold the reset button on your board, next run load/debug script and after the script finishes printing anything, release the reset.

#### Documentation

[Standard library](https://godoc.org/github.com/ziutek/emgo/egroot/src)

[Libraries for STM32, nRF5 and other](https://godoc.org/github.com/ziutek/emgo/egpath/src)

#### Other resources

[Blog](https://ziutek.github.io/)

[YouTube](https://www.youtube.com/channel/UCAW4PLMDGO7_vY4sCG0jg6Q)

[Forum](https://groups.google.com/forum/#!forum/emgo)


emgo

Golang hardware discovery/inspection library.

Robot Operating System (ROS) library for Go.

# goroslib

[![Test](https://github.com/bluenviron/goroslib/workflows/test/badge.svg)](https://github.com/bluenviron/goroslib/actions?query=workflow:test)
[![Lint](https://github.com/bluenviron/goroslib/workflows/lint/badge.svg)](https://github.com/bluenviron/goroslib/actions?query=workflow:lint)
[![Go Report Card](https://goreportcard.com/badge/github.com/bluenviron/goroslib)](https://goreportcard.com/report/github.com/bluenviron/goroslib)
[![CodeCov](https://codecov.io/gh/bluenviron/goroslib/branch/main/graph/badge.svg)](https://app.codecov.io/gh/bluenviron/goroslib/branch/main)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/bluenviron/goroslib/v2)](https://pkg.go.dev/github.com/bluenviron/goroslib/v2#pkg-index)

goroslib is a library in pure Go that allows to build clients (nodes) for the Robot Operating System (ROS).

The Robot Operating System (ROS) is a project that provides a specification to make multiple programs communicate with each other over time, exchanging structured data with topics, services, actions and parameters. It was conceived to link sensors, algorithms and actuators in unmanned ground vehicles (UGVs) and robots, but it is not bounded to the robot world and can be used anywhere there's the need of building streams of data (for example in video processing).

Features:

* publish and subscribe to topics with TCP or UDP
* provide and call services
* provide and call actions
* provide and call simple actions
* get and set parameters
* support namespaces and relative topics
* support IPv6 (stateful addresses only)
* support time API
* compilation of `.msg` files is not necessary, message definitions are extracted from code
* compile or cross-compile for all Go supported OSs (Linux, Windows, Mac OS X) and architectures
* examples provided for every feature, comprehensive test suite, continuous integration

## Table of contents

* [Installation](#installation)
* [API Documentation](#api-documentation)
* [FAQs](#faqs)
  * [Comparison with other libraries](#comparison-with-other-libraries)
  * [Full list of features](#full-list-of-features)
  * [Standard messages, services and actions](#standard-messages-services-and-actions)
  * [Custom messages, services and actions](#custom-messages-services-and-actions)
  * [Import existing messages, services and actions](#import-existing-messages-services-and-actions)
  * [Compile a node for another operating system](#compile-a-node-for-another-operating-system)
  * [Edit the library](#edit-the-library)
* [Specifications](#specifications)
* [Links](#links)

## Installation

1. Install Go &ge; 1.20.

2. Create an empty folder, open a terminal in it and initialize the Go modules system:

   ```
   go mod init main
   ```

3. Download one of the example files and place it in the folder:

   * [subscriber](examples/subscriber/main.go)
   * [subscriber-custom](examples/subscriber-custom/main.go)
   * [subscriber-udp](examples/subscriber-udp/main.go)
   * [subscriber-ipv6](examples/subscriber-ipv6/main.go)
   * [publisher](examples/publisher/main.go)
   * [publisher-custom](examples/publisher-custom/main.go)
   * [serviceclient](examples/serviceclient/main.go)
   * [serviceprovider](examples/serviceprovider/main.go)
   * [simpleactionclient](examples/simpleactionclient/main.go)
   * [simpleactionserver](examples/simpleactionserver/main.go)
   * [param-set-get](examples/param-set-get/main.go)
   * [cluster-info](examples/cluster-info/main.go)

4. Compile and run (a ROS master must be already running in the background)

   ```
   go run name-of-the-go-file.go
   ```

## API Documentation

[Click to open the API Documentation](https://pkg.go.dev/github.com/bluenviron/goroslib/v2#pkg-index)

## FAQs

### Comparison with other libraries

#### goroslib vs official C++/Python libraries

The official project provides libraries to write nodes in C++ and Python, but they require the download of over 1GB of data and work only with a fixed buildchain. This library allows to write lightweight nodes that can be built with the standard Go compiler, do not need any runtime library and have a size of some megabytes. Another advantage lies in the possibility of compiling nodes for all the Golang supported operating systems (Linux, Windows, Mac OS X, etc) and architectures.

#### goroslib vs rosgo

rosgo is currently unmaintained; furthermore, it requires compilation of `.msg` files, doesn't support UDP, doesn't support actions, doesn't support simulated clocks.

### Full list of features

Current and missing features are [described in the FEATURES document](FEATURES.md).

### Standard messages, services and actions

This library provides most of the standard messages, services and actions in the folder `pkg/msgs`:

|package|documentation|repository|
|-------|-------------|----------|
|ackermann_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/ackermann_msgs)|[link](https://github.com/ros-drivers/ackermann_msgs)|
|actionlib|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/actionlib)|[link](https://github.com/ros/actionlib)|
|actionlib_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/actionlib_msgs)|[link](https://github.com/ros/common_msgs)|
|audio_common_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/audio_common_msgs)|[link](https://github.com/ros-drivers/audio_common)|
|control_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/control_msgs)|[link](https://github.com/ros-controls/control_msgs)|
|diagnostic_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/diagnostic_msgs)|[link](https://github.com/ros/common_msgs)|
|geometry_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/geometry_msgs)|[link](https://github.com/ros/common_msgs)|
|geographic_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/geographic_msgs)|[link](https://github.com/ros-geographic-info/geographic_info)|
|mavros_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/mavros_msgs)|[link](https://github.com/mavlink/mavros)|
|nav_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/nav_msgs)|[link](https://github.com/ros/common_msgs)|
|rosgraph_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/rosgraph_msgs)|[link](https://github.com/ros/ros_comm_msgs)|
|sensor_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/sensor_msgs)|[link](https://github.com/ros/common_msgs)|
|shape_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/shape_msgs)|[link](https://github.com/ros/common_msgs)|
|sound_play|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/sound_play)|[link](https://github.com/ros-drivers/audio_common)|
|std_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/std_msgs)|[link](https://github.com/ros/std_msgs)|
|std_srvs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/std_srvs)|[link](https://github.com/ros/ros_comm_msgs)|
|stereo_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/stereo_msgs)|[link](https://github.com/ros/common_msgs)|
|tf|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/tf)|[link](https://github.com/ros/geometry)|
|tf2_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/tf2_msgs)|[link](https://github.com/ros/geometry2)|
|trajectory_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/trajectory_msgs)|[link](https://github.com/ros/common_msgs)|
|uuid_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/uuid_msgs)|[link](https://github.com/ros-geographic-info/unique_identifier)|
|velodyne_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/velodyne_msgs)|[link](https://github.com/ros-drivers/velodyne)|
|vision_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/vision_msgs)|[link](https://github.com/ros-perception/vision_msgs)|
|visualization_msgs|[link](https://pkg.go.dev/github.com/bluenviron/goroslib/v2/pkg/msgs/visualization_msgs)|[link](https://github.com/ros/common_msgs)|

### Custom messages, services and actions

To define custom messages, the standard ROS C++/Python libraries require `.msg` files in this format:

```
bool field1
int32 field2
```

This library doesn't require any `.msg` file, it is enough to write Go structures in this format:

```go
import (
    "github.com/bluenviron/goroslib/v2/pkg/msgs"
)

type MessageName struct {
    msg.Package `ros:"my_package"`
    Field1 bool
    Field2 int32
}
```

The name of the message is taken from the name of the struct (in this case, `MessageName`), but it can be overridden by adding the `msg.Name` field:

```go
type MessageName struct {
    msg.Package `ros:"my_package"`
    msg.Name `ros:"my_message_name"`
    Field1 bool
    Field2 int32
}
```

The type of a field can be one of the following:

* one of the primitive field types: `bool`, `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`, `int64`, `uint64`, `float32`, `float64`, `string`, `time.Time`, `time.Duration`

* another standard or custom message

The name of a field must be in CamelCase, and is converted to snake_case when interacting with C++/Python nodes. If this conversion is not possible, the tag `rosname` can be used to override the field name:

```go
type MessageName struct {
    msg.Package `ros:"my_package"`
    Field bool  `rosname:"FIELD"`
}
```

Services in this format:

```
uint32 input
---
uint32 output
```

Are equivalent to Go structures in this format:

```go
type ServiceNameReq struct {
    Input uint32
}

type ServiceNameRes struct {
	Output uint32
}

type ServiceName struct {
	msg.Package `ros:"my_package"`
	ServiceNameReq
	ServiceNameRes
}
```

Actions in this format:

```
uint32 goal
---
uint32 result
---
uint32 feedback
```

Are equivalent to Go structures in this format:

```go
type ActionNameGoal struct {
	Goal uint32
}

type ActionNameResult struct {
	Result uint32
}

type ActionNameFeedback struct {
	Feedback uint32
}

type ActionName struct {
	msg.Package `ros:"my_package"`
	ActionNameGoal
	ActionNameResult
	ActionNameFeedback
}
```

### Import existing messages, services and actions

You can convert existing `.msg` files into their equivalent Go structures by using the `msg-import` tool:

```
go install github.com/bluenviron/goroslib/v2/cmd/msg-import@latest
msg-import --rospackage=my_package mymessage.msg > mymessage.go
```

You can convert existing `.srv` files into their equivalent Go structures by using the `srv-import` tool:

```
go install github.com/bluenviron/goroslib/v2/cmd/srv-import@latest
srv-import --rospackage=my_package myservice.srv > myservice.go
```

You can convert existing `.action` files into their equivalent Go structures by using the `action-import` tool:

```
go install github.com/bluenviron/goroslib/v2/cmd/action-import@latest
action-import --rospackage=my_package myaction.action > myaction.go
```

To convert a whole ROS package to Go, you can use the `package-import` tool:

```
go install github.com/bluenviron/goroslib/v2/cmd/package-import@latest
package-import <path-to-ros-package>
```

### Compile a node for another operating system

To compile a node for another OS, it's enough to follow the standard Golang procedure to cross-compile, that consists in setting the `GOOS` and `GOARCH` environment variables according to the target machine. For instance, to build a node for Windows from another OS, run:

```
GOOS=windows GOARCH=amd64 go build -o node.exe name-of-source-file.go
```

### Edit the library

If you want to hack the library and test the results, unit tests can be launched with:

```
make test
```

## Specifications

|name|area|
|----|----|
|[Technical overview](https://wiki.ros.org/ROS/Technical%20Overview)|general|
|[Implementing client libraries](https://wiki.ros.org/Implementing%20Client%20Libraries)|general|
|[Names](http://wiki.ros.org/Names)|general|
|[Actionlib](http://wiki.ros.org/actionlib)|action lib|
|[Actionlib detailed description](http://wiki.ros.org/actionlib/DetailedDescription)|action lib|
|[Master API](https://wiki.ros.org/ROS/Master_API)|API|
|[Parameter server API](https://wiki.ros.org/ROS/Parameter%20Server%20API)|API|
|[Slave API](https://wiki.ros.org/ROS/Slave_API)|API|
|[Connection header](https://wiki.ros.org/ROS/Connection%20Header)|protocol|
|[TCPROS](https://wiki.ros.org/ROS/TCPROS)|protocol|
|[UDPROS](https://wiki.ros.org/ROS/UDPROS)|protocol|
|[Wireshark dissector](https://fossies.org/linux/wireshark/epan/dissectors/packet-prototcp.c)|protocol|
|[Golang project layout](https://github.com/golang-standards/project-layout)|project layout|

## Links

Other Go libraries

* [rosgo (v1)](https://github.com/akio/rosgo)
* [rclgo (v2)](https://github.com/juaruipav/rclgo)

Other non-Go libraries

* [official library (v1) (C++)](https://github.com/ros/ros_comm/tree/noetic-devel/clients/roscpp/src/libros) ([documentation](https://docs.ros.org/noetic/api/roscpp/html/classros_1_1NodeHandle.html))
* [official library (v1) (Python)](https://docs.ros.org/noetic/api/rosnode/html/)
* [cros (v1) (C)](https://github.com/ros-industrial/cros)
* [foxglove/ros1 (v1) (TypeScript)](https://github.com/foxglove/ros1)
* [awesome ros2 (v2) (misc)](https://fkromer.github.io/awesome-ros2/)
* [foxglove/ros2 (v2) (TypeScript)](https://github.com/foxglove/ros2)


goroslib

a polled API to read the state of an attached joystick.

# joystick
Go Joystick API

[![GoDoc](https://godoc.org/github.com/0xcafed00d/joystick?status.svg)](https://godoc.org/github.com/0xcafed00d/joystick) [![Build Status](https://travis-ci.org/0xcafed00d/joystick.svg)](https://travis-ci.org/0xcafed00d/joystick)

Package joystick implements a Polled API to read the state of an attached joystick.
Windows, Linux & OSX are supported.
Package requires no external dependencies to be installed.

Mac OSX code developed by:  https://github.com/ledyba

## Installation:
```bash
$ go get github.com/0xcafed00d/joystick/...
```
## Sample Program 
```bash
$ go install github.com/0xcafed00d/joystick/joysticktest
$ joysticktest 0
```
Displays the state of the specified joystick
## Example:
```go
import "github.com/0xcafed00d/joystick"
```
```go
js, err := joystick.Open(jsid)
if err != nil {
  panic(err)
}

fmt.Printf("Joystick Name: %s", js.Name())
fmt.Printf("   Axis Count: %d", js.AxisCount())
fmt.Printf(" Button Count: %d", js.ButtonCount())

state, err := joystick.Read()
if err != nil {
  panic(err)
}

fmt.Printf("Axis Data: %v", state.AxisData)
js.Close()
```


joystick

A pure Go library providing Linux OS / kernel / hardware system information.

# Sysinfo

[![Go Report Card](https://goreportcard.com/badge/github.com/zcalusic/sysinfo)](https://goreportcard.com/report/github.com/zcalusic/sysinfo)
[![GoDoc](https://godoc.org/github.com/zcalusic/sysinfo?status.svg)](https://godoc.org/github.com/zcalusic/sysinfo)
[![License](https://img.shields.io/badge/license-MIT-a31f34.svg?maxAge=2592000)](https://github.com/zcalusic/sysinfo/blob/master/LICENSE)
[![Powered by](https://img.shields.io/badge/powered_by-Go-5272b4.svg?maxAge=2592000)](https://go.dev/)
[![Platform](https://img.shields.io/badge/platform-Linux-009bde.svg?maxAge=2592000)](https://www.linuxfoundation.org/)

Package sysinfo is a Go library providing Linux OS / kernel / hardware system information. It's completely standalone,
has no dependencies on the host system and doesn't execute external programs. It collects only "inventory type"
information, things that don't change often.

## Code Example

```go
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os/user"

	"github.com/zcalusic/sysinfo"
)

func main() {
	current, err := user.Current()
	if err != nil {
		log.Fatal(err)
	}

	if current.Uid != "0" {
		log.Fatal("requires superuser privilege")
	}

	var si sysinfo.SysInfo

	si.GetSysInfo()

	data, err := json.MarshalIndent(&si, "", "  ")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(string(data))
}
```

## Motivation

I couldn't find any self-contained library that would provide set of data/features I needed. So another sysinfo was
born.

The purpose of the library is to collect only inventory info. No metrics like CPU usage or load average will be added.
The rule of thumb is, if it's changing during the day, every day, it doesn't belong in the library.

The library should work well on any modern/supported Linux distribution. There are no plans to add support for older
unsupported Linux distributions/kernels, to keep the code clean and robust and reduce the maintenance burden.

## Requirements

Sysinfo requires:

- Linux kernel 4.2 or later
- access to /sys & /proc Linux virtual file systems
- access to various files in /etc, /var, /run FS hierarchy
- superuser privileges (to access SMBIOS/DMI table and detect RAM size and properties)

Sysinfo doesn't require ANY other external utility on the target system, which is its primary strength, IMHO.

It depends on Linux internals heavily, so there are no plans to support other operating systems.

## Installation

Just use go get.

```
go get github.com/zcalusic/sysinfo
```

There's also a very simple utility demonstrating sysinfo library capabilities. Start it (as superuser) to get pretty
formatted JSON output of all the info that sysinfo library provides. Due to its simplicity, the source code of the
utility also doubles down as an example of how to use the library.

```
go get github.com/zcalusic/sysinfo/cmd/sysinfo
```

--

Build demo utility in Docker container:  https://github.com/mattscilipoti/compile_sysinfo

## Sample output

```json
{
  "sysinfo": {
    "version": "0.9.1",
    "timestamp": "2016-09-24T13:30:28.369498856+02:00"
  },
  "node": {
    "hostname": "web12",
    "machineid": "04aa55927ebd390829367c1757b98cac",
    "timezone": "Europe/Zagreb"
  },
  "os": {
    "name": "CentOS Linux 7 (Core)",
    "vendor": "centos",
    "version": "7",
    "release": "7.2.1511",
    "architecture": "amd64"
  },
  "kernel": {
    "release": "3.10.0-327.13.1.el7.x86_64",
    "version": "#1 SMP Thu Mar 31 16:04:38 UTC 2016",
    "architecture": "x86_64"
  },
  "product": {
    "name": "RH2288H V3",
    "vendor": "Huawei",
    "version": "V100R003",
    "serial": "2103711GEL10F3430658"
  },
  "board": {
    "name": "BC11HGSA0",
    "vendor": "Huawei",
    "version": "V100R003",
    "serial": "033HXVCNG3107624"
  },
  "chassis": {
    "type": 17,
    "vendor": "Huawei"
  },
  "bios": {
    "vendor": "Insyde Corp.",
    "version": "3.16",
    "date": "03/16/2016"
  },
  "cpu": {
    "vendor": "GenuineIntel",
    "model": "Intel(R) Xeon(R) CPU E5-2630 v3 @ 2.40GHz",
    "speed": 2400,
    "cache": 20480,
    "cpus": 1,
    "cores": 8,
    "threads": 16
  },
  "memory": {
    "type": "DRAM",
    "speed": 2133,
    "size": 65536
  },
  "storage": [
    {
      "name": "sda",
      "driver": "sd",
      "vendor": "ATA",
      "model": "ST9500620NS",
      "serial": "9XF2HZ9K",
      "size": 500
    }
  ],
  "network": [
    {
      "name": "enp3s0f1",
      "driver": "ixgbe",
      "macaddress": "84:ad:5a:e3:79:71",
      "port": "fibre",
      "speed": 10000
    }
  ]
}
```

## Contributors

Contributors are welcome, just open a new issue / pull request.

## License

```
The MIT License (MIT)

Copyright © 2016 Zlatko Čalušić

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```


The Best Go Libraries For Hardware (6)

arduino-cli

emgo

ghw

goroslib

joystick

sysinfo