Focus API documentation

Concept

The Focus API is a two-way communication mechanism between the Raise and any computer software that wants to get information or configure/activate the raise's plugins.

It discovers all the EEPROM assigned positions of the memory with specific commands to update or trigger them depending on the kind of plugin that uses them.

This means for example being capable of storing the macros or to be able to trigger them through the serial interface without touching the keyboard or Bazecor.

The focus library is a part of the Keyboard's Firmware but also has a helper class created in JavaScript for the Bazecor, we will show here the commands for the JavaScript Focus API and how to trigger them through the serial interface also, just as an example if you want to retrieve all available commands you have to send the keyboard the string "help".

For JavaScript: focus.command("help")

Serial Command (Unix): echo 'help' > /dev/ttyACM0

The serial interface will always end the current message by a newline feed plus a period.

You can expand on this knowledge in the docs about the kaleidoscope Firmware from which the Raise extends

⚠ Memory usage disclaimer ⚠

When sending focus commands to the keyboard, keep in mind that every time you put data after the command, that stores the information in the keyboard, this means that the flash memory is using up it's lifespan, so avoid loops that save data to the keyboard frequently, so that the chip will last you as long as possible.

Available Methods

Running focus.command("help") will get you the following list of available commands:

Version

The version of the firmware

version

KeyMap Section

KeyMap commands allow you to read/wirte the current keymap stored in the keyboard for each layer

keymap.custom

keymap.default

keymap.onlyCustom

Settings Section

Settings allow you to check the integrity of the EEPROM stored data

settings.defaultLayer

Leds Section

Commands to help you with the testing and settings of the raise's leds

Colors Section

Commands to read/write the color palette and colorMap from the raise to change it's static colors

palette

colormap.map

Led time to remain lit

Time to wait until turning the led's off

idleleds.time_limit

Hardware Section

Hardware commands that allow you to perform certain operations like retrieving side's versions, watch power consumption, etc..

hardware.sled_current

Plugins section

Plugin's section to configure them, like the DynamicMacros plugin.

Sides Section

Hardware commands specific to the sides for flashing them.

hardware.flash_left_side

hardware.flash_right_side

hardware.verify_left_side

hardware.verify_right_side

Help

Help command to display this list

help

Layers Section

Layer commands to switch between them (for example when changing a from a program to another and more goodies)

version

Returns the version of the Raise firmware stored in the keyboard's EEPROM

Commands

JavaScript:
```
focus.command("version")
```
Serial Command (Unix):
```
echo 'version' > /dev/ttyACM0
```

Expected output

it should give back 3 strings,

Bazecor Version:
```
'0.2.5'
```
Kaleidoscope's newest Git commit incorporated
```
'6bd1f81e'
```
Raise's Firmware newest Git commit
```
'fe423ce-dirty'
```
Dirty here means it was custom-built with the makefile, not built automatically by Travis.

keymap.custom

This command of the focus API has two functions, when sent alone, it retrieves the whole custom keymap stored in the keyboard, when sent with the map as trailing numbers (in the same format as received) it will update the custom keymap stored in the EEPROM.

To know the actual correlation between the position of the map sent and the actual keys in the keyboard, look here

Commands

To retrieve:

JavaScript:
```
focus.command("keymap.custom")
```
Serial Command (Unix):
```
echo 'keymap.custom' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("keymap.custom N N N N N N N N N N N N N N N")

Serial Command (Unix):

echo 'keymap.custom N N N N N N N N N N N N N N N' > /dev/ttyACM0

Being

 'N N N...'

the 16bit numbers that represent each key assigned to that position of the keymap the numbers amount 80(keys per layer)x10(custom layers)

Expected output

It should give back the whole custom keymap (80 key positions for each layer and all 10 layers) if sent alone, if sent with the keymap of the same length as received, it should return a nextline, period.

keymap.default

This command works in the same way as keymap.custom, but affecting the default layers stored in the -1 and -2 positions of the layer stack.

To know the actual correlation between the position of the map sent and the actual keys in the keyboard, look here

Command

To retrieve:

JavaScript:
```
focus.command("keymap.default")
```
Serial Command (Unix):
```
echo 'keymap.default' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("keymap.default N N N N N N N N N N N N N N N")

Serial Command (Unix):

echo 'keymap.default N N N N N N N N N N N N N N N' > /dev/ttyACM0

Being

 'N N N...'

the 16bit numbers that represent each key assigned to that position of the keymap the numbers amount 80(keys per layer)x2(default layers)

Expected output

It should give back the two default layers keymap (80 key positions for each layer for the two default layers) if sent alone, if sent with the keymap of the same length as received, it should return a nextline, period.

keymap.onlyCustom

This command returns true or false depending on the user setting of hiding the default layers or not, it does not allow you to increment the number of available layers by start using the default ones, they are there so you can store a backup for two layers in your keyboard

Commands

To retrieve:

JavaScript:
```
focus.command("keymap.onlyCustom")
```
Serial Command (Unix):
```
echo 'keymap.onlyCustom' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("keymap.onlyCustom true")
```

Serial Command (Unix):

echo 'keymap.onlyCustom trure' > /dev/ttyACM0

Expected output

It should return the current state of the onlyCustom boolean variable stored in the keyboard, being it true or false, when sending the value added to the command, it should return a nextline, period.

settings.defaultLayer

This command returns the default layer the keyboard will boot in, with this you can change the default layer in which the Raise starts working to any custom layer that you want.

Commands

To retrieve:

JavaScript:
```
focus.command("keymap.defaultLayer")
```

Serial Command (Unix):

echo 'keymap.defaultLayer' > /dev/ttyACM0

To set:

JavaScript:
```
focus.command("keymap.defaultLayer 1")
```

Serial Command (Unix):

echo 'keymap.defaultLayer 1' > /dev/ttyACM0

Expected output

It should return the current default layer stored in the EEPROM, if it's send with the new default layer, it should return a nextline, period.

settings.valid?

This command returns a boolean value that states true if all checks have been performed to the current settings and it's upload was done in the intended way

Commands

To retrieve:

JavaScript:
```
focus.command("settings.valid")
```
Serial Command (Unix):
```
echo 'settings.valid' > /dev/ttyACM0
```

Expected output

It should return true if you changed your settings with Bazecor, if not, it can return false, but is currently not in use.

settings.version

This command returns the current settings version, it allows Bazecor to identify any changes in the expected output to understand them and shape to them.

Commands

To retrieve:

JavaScript:
```
focus.command("settings.version")
```
Serial Command (Unix):
```
echo 'settings.version' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("settings.version 1")
```

Serial Command (Unix):

echo 'settings.version 1' > /dev/ttyACM0

Expected output

It should return the current settings version stored in the EEPROM.

settings.crc

Returns the CRC checksum of the layout.

Commands

To retrieve:

JavaScript:
```
focus.command("settings.crc")
```
Serial Command (Unix):
```
echo 'settings.crc' > /dev/ttyACM0
```

Expected output

It should the check of each one of the memory positions reserved in the eeprom, for example 6228/6228

eeprom.contents

This command returns the whole EEPROM contents. and allows you to send them in one go.

Commands

To retrieve:

JavaScript:
```
focus.command("eeprom.contents")
```
Serial Command (Unix):
```
echo 'eeprom.contents' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("eeprom.contents NNNNNNNNNNNNN")

Serial Command (Unix):

echo 'eeprom.contents NNNNNNNNNNNN' > /dev/ttyACM0

Expected output

It should return the whole EEPROM length of contents, in this case as CRC returned, 6228 bytes.

eeprom.free

This command returns the remaining EEPROM bytes left.

Commands

To retrieve:

JavaScript:
```
focus.command("eeprom.free")
```
Serial Command (Unix):
```
echo 'eeprom.free' > /dev/ttyACM0
```

Expected output

It should return the free EEPROM memory, 2793 bytes in my case.

led.at

This command returns the color that an individual led has right now in RGB code, also allows you to change that individual led's color with the rgb color following it's position.

Commands

To retrieve:

JavaScript:
```
focus.command("led.at 21")
```
Serial Command (Unix):
```
echo 'led.at 21' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("led.at 21 255 255 0")
```

Serial Command (Unix):

echo 'led.at 21 255 255 0' > /dev/ttyACM0

Expected output

With this function you can change, based on external events, a led color depending on code outside raise's firmware.

if sent only with the LED number, it will return its color

80 227 194

if sent with the color coded (ex: 255 255 0 or yellow) it will change that numbered LEDs color to yellow.

led.getMultiple

This command returns the colors of each of the numbered LED's that are listed in RGB code.

Commands

To retrieve:

JavaScript:

focus.command("led.getMultiple 1 2 3 4 5")

Serial Command (Unix):

echo 'led.getMultiple 1 2 3 4 5' > /dev/ttyACM0

Expected output

With this function you can read the color of a given set of LED's and will return the following:

1 # 80 227 194
2 # 80 227 194
3 # 80 227 194
4 # 80 227 194
5 # 80 227 194

led.setMultiple

This command applies the defined color to all of the numbered LEDs listed afterwards

Commands

To set:

JavaScript:

focus.command("led.setMultiple 255 0 0 1 2 3 4 5")

Serial Command (Unix):

echo 'led.setMultiple 255 0 0 1 2 3 4 5' > /dev/ttyACM0

Expected output

After execution, listed LEDs should physically change their color to the selected one (255 0 0 or RED) on the keyboard, will return newline, period.

led.setAll

This command sets all leds to a certain color transmitted by RGB.

Commands

To set:

JavaScript:
```
focus.command("led.setAll 255 255 255")
```

Serial Command (Unix):

echo 'led.setAll 255 255 255' > /dev/ttyACM0

Expected output

The keyboard will change color when the command is sent successfully, will return newline, period.

led.mode

This command reads/writes the current led mode, which changes the type of led layout the keyboard shows, you can switch between the different led effects with this function, like rainbow, etc... does the same as LedEffect.Next key in Bazecor.

Commands

To retrieve:

JavaScript:
```
focus.command("led.mode")
```
Serial Command (Unix):
```
echo 'led.mode' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("led.mode 2")
```
Serial Command (Unix):
```
echo 'led.mode 2' > /dev/ttyACM0
```

Expected output

The keyboard will either return the current effect being displayed following it's coding, or it will change the current efect following that coding also.

Effect encoding	Effect description
0	Per Layer colors, they change when you switch between layers
1	Rainbow Wave effect
2	Rainbow effect (single color)
3	Stalker effect (keys lit when pressed and then fade out)
4	Heatmap effect (keys lit when pressed following a gardient between red and faint blue based on the most pressed key order explanation code )
5	Digital Rain effect
6	Sprinkling water effect when pressed

* The only FW that supports effects 4, 5 and 6 is the Raise stable FW, but it will be implemented on the rest of the FW's in the near future

led.brightness

This command reads/writes the brightness setting for the Backlight LEDs stored in the EEPROM

When applied to the Defy keyboard, additional commands are available to modify the behavior when in wireless mode, this one remains and only affects wired mode.

Commands

To retrieve:

JavaScript:
```
focus.command("led.brightness")
```
Serial Command (Unix):
```
echo 'led.brightness' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("led.brightness 210")
```

Serial Command (Unix):

echo 'led.brightness 210' > /dev/ttyACM0

Expected output

This function allows you to get/set the current brightness of the backlight LEDs of your keyboard.

the return value will be the same as the sent one, a 8 bit integer (number between 0 and 255)

led.brightnessUG

This command reads/writes the brightness setting for the Underglow stored in the EEPROM

When applied to the Defy keyboard, additional commands are available to modify the behavior when in wireless mode, these one remain and only affect wired mode.

Commands

To retrieve:

JavaScript:
```
focus.command("led.brightnessUG")
```
Serial Command (Unix):
```
echo 'led.brightnessUG' > /dev/ttyACM0
```

To set:

JavaScript:
```
focus.command("led.brightnessUG 210")
```

Serial Command (Unix):

echo 'led.brightnessUG 210' > /dev/ttyACM0

Expected output

This function allows you to get/set the current brightness of the Underglow LEDs of your keyboard.

the return value will be the same as the sent one, a 8 bit integer (number between 0 and 255)

led.theme

This command reads/writes the whole LED color assignment currently in use on the keyboard, its encoded using RGB values.

Commands

To retrieve:

JavaScript:
```
focus.command("led.theme")
```
Serial Command (Unix):
```
echo 'led.theme' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("led.theme NNN NNN NNN NNN NNN NNN")

Serial Command (Unix):

echo 'led.theme NNN NNN NNN NNN NNN NNN' > /dev/ttyACM0

Expected output

With this function you can get/set, whole LED lighting theme using a single command independently of the palette data stored in the keyboard's EEPROM.

when you ask for the values using led.theme you are expected to receive:

248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 248 231 28 248 231 28 248 231 28 80 227 194 248 231 28 255 107 0 248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 80 227 194 80 227 194 80 227 194 80 227 194 80 227 194 248 231 28 248 231 28 248 231 28 248 231 28 248 231 28 80 227 194 248 231 28 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 255 107 0 0 0 0

Which is the full RGB map of the values currently being represented by each LED, its encoding is RGB so each 3 values represent a single LED.

The command will expect you to send back the same quantity of LEDs, if any is lacking, they will not get reassigned.

palette

This command reads/writes the color palette that is used by the color map to establish each color that can be assigned to the keyboard.

Commands

To retrieve:

JavaScript:
```
focus.command("palette")
```
Serial Command (Unix):
```
echo 'palette' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("led.palete NNN NNN NNN NNN NNN NNN")

Serial Command (Unix):

echo 'palette NNN NNN NNN NNN NNN NNN' > /dev/ttyACM0

Expected output

This command reads / writes the palette stored in the eeprom, this means the command can change the lighting theme without changing the actual positions on which each color is assigned, you have to provide the whole palette when storing it.

colormap.map

This command reads/writes the colorMap that assigns each color listed in the palette to individual leds mapping them to the keyboard's current layout.

To know the actual correlation between the position of the map sent and the actual keys in the keyboard, look here

Commands

To retrieve:

JavaScript:
```
focus.command("colormap.map")
```
Serial Command (Unix):
```
echo 'colormap.map' > /dev/ttyACM0
```

To set:

JavaScript:

focus.command("colormap.map N N N N N N N N N N N N N N N N N N")

Serial Command (Unix):

echo 'colormap.map N N N N N N N N N N N N N N N N N N' > /dev/ttyACM0

Expected output

This command allows you to assign each led to a different color stored in the palette, you have to provide the whole colormap when storing it.

idleleds.time_limit

This command reads/writes the idle led time to be turned off in seconds.

Commands

To retrieve:

JavaScript:
```
focus.command("idleleds.time_limit")
```

Serial Command (Unix):

echo 'idleleds.time_limit' > /dev/ttyACM0

To set:

JavaScript:

focus.command("idleleds.time_limit 600")

Serial Command (Unix):

echo 'idleleds.time_limit 600' > /dev/ttyACM0

Expected output

returns the current time stored in the EEPROM and allows you to set it to another time, not exceding 65k seconds