Requirements

PROS 4.x or later, or VEXcode (VEXcode V5, VEXcode Pro V5, or the VEX VS Code extension)
VEX V5 brain
WS2812B-compatible LED strip wired to a VEX ADI port

Install via PROS CLI

pros c fetch https://github.com/advisorylabs/hitlib/releases/download/1.5.0/hitlib@1.5.0.zip

pros c apply hitlib

Or paste the URL directly into the Install Template dialog in the PROS VS Code extension.

Check the Releases page for the latest version and swap the version number above if a newer one is available.

Install into a VEXcode project

VEXcode has no template system, so HitLib ships as source for it. Download hitlib-vexcode@1.5.0.zip from the Releases page and copy its two folders into your project:

your-project/
├─ include/hitlib/     ← from the zip
└─ src/hitlib/         ← from the zip

The VEXcode makefile already builds src/*/*.cpp and searches include/, so there is nothing to configure. HitLib notices it is building against the VEX SDK and uses it in place of PROS.

In this download every header ends in .h rather than .hpp, because VEXcode Pro V5 only shows .h files in its file tree. Wherever these docs include hitlib/hitapi.hpp or hitlib/profiles/classic.hpp, a VEXcode project includes hitlib/hitapi.h and hitlib/profiles/classic.h. Then, in main.cpp:

#include "vex.h"
#include "hitlib/hitapi.h"
 
hitlib::LedStrand strand(1, 63);   // 3-wire port A, 63 LEDs
hitlib::LedGroup  group;
 
int main() {
    vexcodeInit();
    group.add(&strand);
    group.init();
    group.start();
 
    group.rainbow(1);
 
    while (true) vex::this_thread::sleep_for(100);   // keep main() from exiting
}

Ports are numbered 1-8 for A-H. Don't also configure that port as a device in VEXcode's device menu; HitLib drives it directly.

Include the library

Add one include at the top of your main.h or any file that uses hitlib:

#include "hitlib/hitapi.hpp" // hitlib/hitapi.h in VEXcode

hitapi.hpp

Top-level convenience header, includes the full hitlib public API.

To use the built-in profiles, also include:

#include "hitlib/profiles/classic.hpp" // hitlib/profiles/classic.h in VEXcode

classic.hpp

Ready-made Classic, Modern and Showy LED profiles.

ADI expander

If your strip is on an ADI expander connected to a smart port:

// Smart port 2, ADI port A (1), 63 LEDs

hitlib::LedStrand strand({2, 1}, 63);

The braces matter: three bare numbers always mean (adiPort, length, refreshMs) on the brain's own ports.

Minimal working example

#include "main.h"
#include "hitlib/hitapi.hpp"
 
hitlib::LedStrand strand(6, 63);
hitlib::LedGroup  group;
 
void initialize() {
    group.add(&strand);
    group.init();
    group.start();
}
 
void opcontrol() {
    group.rainbow(1);
}

Pattern Studio

Pattern Studio is a desktop GUI for designing and live-previewing LED profiles without flashing a brain, then exporting them as ready-to-include HitLib C++.

Download a prebuilt build from the Releases page - HitLibPatternStudio-*-windows.zip for Windows, -macos-apple-silicon.zip or -macos-intel.zip for macOS 13 or later - or run it from source on any platform:

git clone https://github.com/advisorylabs/hitlib.git
cd hitlib/tools/pattern_studio
pip install -e .
pattern-studio

The Mac build is not signed with an Apple developer certificate, so macOS blocks the first launch. Drag the app into Applications, double-click it and dismiss the warning, then open System Settings > Privacy & Security, scroll to Security and click Open Anyway. Confirm when macOS asks again and enter your Mac password. It opens normally after that.

Getting a design onto the robot

Point Pattern Studio at your project - drag the project folder onto the window, or Export > Choose Robot Project.... It recognises a PROS project.pros, a VEXcode .v5code file, and a VS Code VEX extension project's .vscode/vex_project_settings.json, and remembers the project between runs.
Export > Deploy. The header lands in the project's include/ as hitlib_studio.hpp, or hitlib_studio.h in a VEXcode project - VEXcode Pro V5 lists only .h headers in its file tree, so Deploy also adds it to the project's .v5code file list.
Paste the two lines it shows you into main.cpp, once:

#include "hitlib_studio.hpp"   // hitlib_studio.h in VEXcode
 
void initialize() { hitlib::studio::begin(); }   // pre_auton() in VEXcode

Deploying again overwrites that header and main.cpp does not change: begin() builds every strand from the design's port, length, refresh interval and brightness, attaches each profile and activates its first mode.

To own the wiring yourself, hitlib::studio::begin(yourGroup) puts the design's strands into your group, and #define HITLIB_STUDIO_NO_AUTOWIRE before the include leaves only the profile and the constexpr constants to build your own LedStrand from. Export > Export Current Strand as C++... (or Export All Strands as C++...) still saves through a normal file dialog for a project the app cannot see. See Profiles & Modes for the full shape of the generated file.

Building a PROS template from source

If you want to build hitlib yourself rather than using a release zip: this repo isn't set up as a pros make-managed project, so it's a plain library build followed by manual packaging.

# Clone the repo
git clone https://github.com/advisorylabs/hitlib.git
cd hitlib
 
# Build bin/hitlib.a requires an arm-none-eabi-gcc toolchain on PATH
# (installed alongside PROS, or via your package manager)
make
 
# Package it as an installable PROS template
mkdir -p template_pkg/include template_pkg/firmware
cp -r include/hitlib template_pkg/include/
cp bin/hitlib.a template_pkg/firmware/
cp template.pros template_pkg/
cd template_pkg && zip -r ../hitlib@1.5.0.zip .

This produces hitlib@1.5.0.zip in the project root (matching the version field in template.pros), which you can then fetch with the CLI as shown above. The archive goes in firmware/ because that is the only place a PROS project links archives from, and only include/hitlib/ is packaged: the rest of include/ is the PROS kernel's, which every project already has.

Building the VEXcode download from source

The VEXcode download is the library's sources, with the headers renamed to .h. No toolchain is needed, only Python 3:

python tools/package_vexcode.py vexcode_pkg

vexcode_pkg/ then holds the include/hitlib/ and src/hitlib/ folders to copy into a VEXcode project, exactly as the release zip does. Give it your project's folder instead to install or update HitLib there directly: it replaces those two folders and leaves everything else in the project alone.