Skip to content

Bluemicro

Jump to bottom
joric edited this page Jul 19, 2024 · 260 revisions

This article is about (nRFMicro-compatible) Bluemicro firmware. Read about Bluemicro hardware in the Alternatives article.

Repository

This is Adafruit nRF52 Arduino package-based firmware. You can build it either with build script or with Arduino IDE.

For split keyboards just use "left" as master and "right" as slave. There are usually three configurations: "master", "left" and "right". For standard keyboards, like a 60%, "master" is just a regular layout, in split configurations it is in fact "standalone", it's a single test layout with no layers or any special keys that's used to test that your hardware works fine (every key does register).

Building

Prerequisites

Building from Arduino IDE

Open the BlueMicro_BLE\firmware\firmware.ino file in Arduino IDE, then:

  • copy the following files from your favorite keyboard example in the keyboard folder into the "firmware" folder, same place as the ino file:
    • keyboard_config.h
    • keymap.cpp
    • keymap.h
  • choose the correct board: "Nordic nRF52840DK (PCA10056)". Don't choose nrf52840 feather - they mix GPIO/Pin numbers...
  • compile
  • select your serial port where your board is connected (double press reset to see the port)
  • upload via serial port in Arduino IDE (press "upload" button)

Uploading via serial port is possible for all the boards because Adafruit UF2 bootloader also supports uploading via DFU (when you press reset twice there's an extra virtual COM port that arrives along with the USB drive).

You can also export hex binary in Arduino IDE via Sketch->Export compiled binary, it saves hex file (into the .ino directory) that you may convert to UF2 with uf2conv.py for uploading. You can also modify upload scripts (boards.txt and platform.txt) in %localappdata%\Arduino15\packages\adafruit\hardware\nrf52 (e.g. send "dfu" reset command to the debug port, etc.).

To make firmwares for left and right halves just edit keyboard_config.h and rebild ("master" is for non-split keyboards).

#define KEYBOARD_SIDE LEFT
//#define KEYBOARD_SIDE RIGHT
// CHANGE THIS FOR THE KEYBOARD TO MATCH WHAT IS BEING FLASHED. OPTIONS: LEFT  RIGHT  MASTER

Building from command line

This script is supposed to run from the Bluemicro root. You have to specify keyboard name and role (left/right).

@echo off
set root=%~dp0
cd %root%/build/windows
set keyboard=crkbd
set keymap=jpconstantineau
set role=left
powershell ./build.ps1 %keyboard%:%keymap%:%role% -nrf52840
set path=C:\SDK\gcc-arm-none-eabi-8-2018-q4-major-win32\bin;%path%
cd %root%
set file=%root%/output/crkbd/%keyboard%-%keymap%-%role%.hex
python ./uf2conv.py %file% -c -f 0xADA52840 || exit
echo Waiting for the UF2 drive. Press Reset twice...
echo dfu| plink.exe -serial com9 > nul 2>&1
:loop
if not exist e:\ goto :loop
timeout 1
copy flash.uf2 e:\

nRFMicro configuration

Required

  • Switch to USE_LFRC in %localappdata%\Arduino15\packages\adafruit\hardware\nrf52\0.20.1\variants\pca10056\variant.h:
//#define USE_LFXO      // Board uses 32khz crystal for LF
#define USE_LFRC    // Board uses RC for LF

This firmware uses XTAL (external 32.768 KHz crystal) by default. If you don't have it on the board it can advertise via Bluetooth but would not be able to connect. Since there's no XTAL on some revisions of nRFMicro, you need to edit pca10056\variant.h in the board package and set USE_LFRC as default:

You can't just replace pca10056 with feather52840sense, cplaynrf52840 or cluenrf52840 in the build script, these boards don't use XTAL but they are not supported by this firmware (it uses pca10056 pin definitions).

  • Edit keyboard configuration in keyboard_config.h: #define HARDWARE_MAPPING NRFMICROV0_3 if you use board flipped with solder jumpers, you have to edit pins (see Pinout), there's no flipped nRFMicro yet. The file is breakout_mapping.h.
    #elif HARDWARE_MAPPING == NRFMICROV0_3
        #define BATTERY_TYPE BATT_UNKNOWN
        #define VBAT_PIN  26
    ...

Misc

  • To blink with nRFMicro's onboard LED on start put this into firmware_main.cpp:
void setup() {
    ...
    #define LED_PIN (32+10) //1.10  = 32+10
    pinMode(LED_PIN, OUTPUT);
    for (int i=0; i<4; i++) { digitalWrite(LED_PIN, i%2 ? LOW : HIGH ); delay(200); }
    ...
}
  • Use this to enable charger in nRFMicro 1.3+ revisions (put it next to the code above):
    #define PROG_PIN 5 // 0.05
    pinMode(PROG_PIN, OUTPUT);
    digitalWrite(PROG_PIN, 0); // enable charger (set PROG to ground)
  • Use this to enable VCC power mosfet:
    #define POWER_PIN 32+9 // 1.09
    pinMode(POWER_PIN, OUTPUT);
    digitalWrite(POWER_PIN, 0); // enable power (0-enable, 1-disable)

Issues

Bluetooth

If the board doesn't connect you probably need to disable external crystal (XTAL, see nRFMicro configuration above).

Build system

Building in Arduino IDE is a killer feature no doubt (also built in DFU uploading), but if you're using Arduino IDE, you have to copy keyboard files to the main folder (this the official way for now, so don't blame me on that). Copying doesn't seem too convenient, you also have to compile twice, for left and right halves, use this define in keyboard_config.h:

#define KEYBOARD_SIDE LEFT
//#define KEYBOARD_SIDE RIGHT

Adding includes to firmware.ino probably could be better (could also select hardware configuration there), maybe even use a local config.h so one could contribute keymaps and build things in IDE without altering the repository (not implemented).

Videos

Installing and Testing Arduino IDE for BlueMicro Firmware

More videos: https://www.youtube.com/channel/UCFpGp4hHe03nvF9c8_gF_jA

MSC

It would be cool to read JSON-formatted layouts from MSC (Mass Storage Class, aka USB drive). My take on that (in progress):

I was under impression I could just implement write/read memory location in msc handlers but apparently there's much more than that. It kind of works though (saves and loads data from the internal filesystem) but it doesn't modify FAT entries properly. Still could work with a couple of predefined filenames.

Clone this wiki locally