Kaleidoscope/README.md

# Kaleidoscope-HostOS

[![Build Status][travis:image]][travis:status]

 [travis:image]: https://travis-ci.org/keyboardio/Kaleidoscope-HostOS.svg?branch=master
 [travis:status]: https://travis-ci.org/keyboardio/Kaleidoscope-HostOS

The `HostOS` extension is not all that useful in itself, rather, it is a
building block other plugins and extensions can use to not repeat the same
guesswork and logic. Its primary purpose is to help either detect, or keep track
of the host operating system. The detection part is not the most reliable thing,
mind you.

The goal is to have a single place that remembers the host OS, either detected,
or set by the end-user, in a Sketch, or via a macro, or some other way. This
information can then be reused by other plugins.

See the [Unicode][plugin:unicode] extension for an example about how to use
`HostOS` in practice.

 [plugin:unicode]: https://github.com/keyboardio/Kaleidoscope-Unicode

## Using the extension

The extension provides a `HostOS` singleton object. It can either be a simple
one without auto-detection (the default), or one that will try to detect the
Host OS, using the [FingerprintUSBHost][fprdetect] library. To enable
auto-detection, `KALEIDOSCOPE_HOSTOS_GUESSER` must be defined before including
the `HostOS` library header.

 [fprdetect]: https://github.com/keyboardio/FingerprintUSBHost

```c++
#define KALEIDOSCOPE_HOSTOS_GUESSER 1

#include <Kaleidoscope.h>
#include <Kaleidoscope-HostOS.h>
#include <Kaleidoscope/HostOS-select.h>

void someFunction(void) {
  if (HostOS.os() == kaleidoscope::hostos::LINUX) {
    // do something linux-y
  }
  if (HostOS.os() == kaleidoscope::hostos::OSX) {
    // do something OSX-y
  }
}

KALEIDOSCOPE_INIT_PLUGINS(HostOS);

void setup(void) {
  Kaleidoscope.setup ();
}
```

To be able to choose between the two variants, one must also include the
`Kaleidoscope/HostOS-select.h` header.

## Extension methods

The extension provides the following methods on the `HostOS` singleton:

### `.os()`

> Returns the stored type of the Host OS.

### `.os(type)`

> Sets the type of the host OS, overriding any previous value. The type is then
> stored in EEPROM for persistence.

## Host OS Values

The OS type (i.e. the return type of `.os()` and the arguments to `.os(type)`) will be one of the following:

   - `kaleidoscope::hostos::LINUX`
   - `kaleidoscope::hostos::OSX`
   - `kaleidoscope::hostos::WINDOWS`
   - `kaleidoscope::hostos::OTHER`

## Focus commands

The plugin provides the `FocusHostOSCommand` object, which, when enabled,
provides the `hostos.type` Focus command.

### `hostos.type [type]`

> Without argument, returns the current OS type set (a numeric value).
>
> With an argument, it sets the OS type.
>
> This command can be used from the host to reliably set the OS type within the firmware.

## Dependencies

* [Kaleidoscope-EEPROM-Settings](https://github.com/keyboardio/Kaleidoscope-EEPROM-Settings)

## Further reading

Starting from the [example][plugin:example] is the recommended way of getting
started with the extension.

 [plugin:example]: https://github.com/keyboardio/Kaleidoscope-HostOS/blob/master/examples/HostOS/HostOS.ino