B9X Electronics Documentation

B9X Basic GUI Module — Complete B9X Basic Language Reference

Complete developer documentation for writing B9X Basic applications on the B9X Basic GUI Module, including the B9X Basic language and the public functions supplied by this module.

1. Language fundamentals

B9X Basic is its own BASIC language. Do not assume that a statement or function from Visual Basic, QBASIC, or another BASIC dialect exists unless it is documented here.

Program structure

A program contains executable statements and may also contain SUB and FUNCTION definitions. Most simple statements end with a semicolon. Block delimiters such as THEN, ELSE, ENDIF, DO, WEND, NEXT, END SUB, and END FUNCTION do not use a semicolon.

' Minimal program
let greeting$ = "Hello from B9X";
counter = 3;
print greeting$;
print counter;

Identifiers and literals

Comments

' comment to end of line
// comment to end of line
/* block comment
   across lines */

Truth values

There is no separate Boolean type. Zero is false; any nonzero numeric value is true. Comparisons and logical operations produce numeric 0 or 1.

2. Variables, strings and arrays

Numeric variables

Ordinary numeric values use double-precision floating-point numbers.

x = 12.5;
scientific = 1.2e3;
negative = -7;

String variables

String names end in $. String assignment uses LET. The usable string value is limited to 512 characters.

let first$ = "B9X";
let message$ = first$ + " Basic";

Assignment

count = 1;
let count = count + 1;
let label$ = "ready";

Numeric arrays

DIM creates a one-dimensional numeric array. The declared upper bound is inclusive. String arrays are not implemented.

dim samples[9];
for i = 0 to 9 do
    samples[i] = i ** 2;
next
print samples[4];

The largest legal declared bound is 1023.

Scope

Variables created outside a function are global. FUNCTION parameters have their own temporary parameter values while the function executes. A function may read or modify other global variables. SUB has no parameters.

3. Expressions and operators

result = 2 + 3 * 4;
power = 2 ** 3 ** 2;
if temperature >= 25 and enabled == 1 then
    print "warm and enabled";
endif
let full$ = "B9X " + "Basic";

4. Statements and control flow

PRINT

print "ready";
print 2 + 2;

IF / THEN / ELSE / ENDIF

if distance < 20 then
    print "near";
else
    print "far";
endif

WHILE / DO / WEND

count = 0;
while count < 5 do
    print count;
    count = count + 1;
wend

FOR / TO / STEP / NEXT

for i = 1 to 5 do
    print i;
next

for j = 10 to 0 step -2
    print j;
next

STEP defaults to 1. Positive and negative steps are supported. Avoid STEP 0.

Explicit blocks

{
    x = 1;
    print x;
}

Statements not defined by this language

GOTO, GOSUB, INPUT, DATA/READ, SELECT CASE, BREAK, CONTINUE, and line-numbered program flow are not part of the documented grammar. Use structured blocks, SUB, and FUNCTION.

5. SUB and user FUNCTION

SUB

A SUB is a named, argument-free procedure. Call it with CALL.

sub blink()
    setHigh(2);
    wait(100);
    setLow(2);
end sub

call blink();

Numeric FUNCTION

function clamp(value, low, high)
    if value < low then
        return low;
    endif
    if value > high then
        return high;
    endif
    return value;
end function

print clamp(120, 0, 100);

String FUNCTION

A string-returning function ends in $. Parameters ending in $ are string parameters.

function greeting$(name$)
    return "Hello, " + name$;
end function

let text$ = greeting$("B9X");

• User functions may accept up to 8 parameters.
• A missing numeric return falls back to 0; a missing string return falls back to an empty string.
• Define a FUNCTION before code that calls it.

6. Core string, formatting and time functions

FMT$ tokens

0 required digit; # optional digit; . decimal; , grouping; % percent; leading + forces sign; E/e scientific notation; semicolon-separated sections may specify positive/negative/zero formats.

7. B9X Basic GUI Module public function reference

The signatures below are taken from the public B9X Basic registrations in the supplied GUI Module project. number means a numeric argument and string means a string argument.

GUI Module

displayAddButton(value1, value2, value3, value4, value5, text6$, value7)

retVal = displayAddButton(1, 20, 40, 130, 45, "START", 2);

displayAddLabel(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddLabel(2, 20, 100, 280, 35, "Ready", 2, 65535);

displayAddCheckBox(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddCheckBox(3, 20, 150, 180, 40, "Enable", 0, 2);

displayAddSlider(value1, value2, value3, value4, value5, value6, value7, value8)

retVal = displayAddSlider(4, 10, 210, 298, 51, 0, 100, 50);

displayAddTextBox(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddTextBox(5, 20, 280, 280, 42, "", 32, 2);

displayAddPasswordTextBox(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddPasswordTextBox(6, 20, 335, 280, 42, "", 32, 2);

displayAddIcon(value1, value2, value3, value4)

retVal = displayAddIcon(7, 111, 390, 17);

displaySetIcon(value1, value2)

retVal = displaySetIcon(7, 18);

displayAddBmpFromFile(value1, value2, value3, text4$, value5)

retVal = displayAddBmpFromFile(8, 10, 30, "/sdcard/photo.bmp", 1);

displayAddBMPFromSD(value1, value2, value3, text4$, value5)

retVal = displayAddBMPFromSD(9, 10, 100, "/sdcard/photo.bmp", 1);

displayAddListBox(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddListBox(1, 2, 3, 4, 5, "text", 7, 8);

displayAddAnalogMeter(value1, value2, value3, value4, value5, value6, value7, value8)

retVal = displayAddAnalogMeter(1, 2, 3, 4, 5, 6, 7, 8);

displayAddVerticalBarMeter(value1, value2, value3, value4, value5, value6, value7, value8)

retVal = displayAddVerticalBarMeter(1, 2, 3, 4, 5, 6, 7, 8);

displayAddLamp(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddLamp(1, 2, 3, 4, 5, "text", 7, 8);

displayAddSwitch(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddSwitch(1, 2, 3, 4, 5, "text", 7, 8);

displayAddToggleSwitch(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddToggleSwitch(1, 2, 3, 4, 5, "text", 7, 8);

displayAddRoundedButton(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddRoundedButton(1, 2, 3, 4, 5, "text", 7, 8);

displayAddFlipSwitch(value1, value2, value3, value4, value5, text6$, value7, value8)

retVal = displayAddFlipSwitch(1, 2, 3, 4, 5, "text", 7, 8);

displayAddKeyboard(value1, value2)

retVal = displayAddKeyboard(30, 5);

displaySetText(value1, text2$)

retVal = displaySetText(2, "Running");

displayClear(value1)

retVal = displayClear(0);

displayRemoveAllElements()

retVal = displayRemoveAllElements();

displayRefresh()

retVal = displayRefresh();

displaySetColors(value1, value2, value3)

retVal = displaySetColors(1, 65535, 0);

displaySetValue(value1, value2)

retVal = displaySetValue(4, 75);

displayGetValue(value1)

retVal = displayGetValue(4);

displaySetChecked(value1, value2)

retVal = displaySetChecked(3, 1);

displayGetChecked(value1)

retVal = displayGetChecked(3);

displaySetEnabled(value1, value2)

retVal = displaySetEnabled(1, 1);

displaySetVisible(value1, value2)

retVal = displaySetVisible(1, 1);

displaySetBrightness(value1)

retVal = displaySetBrightness(80);

displayText(text1$)

retVal = displayText("value");

getDisplayMessage$()

let s$ = getDisplayMessage$();

displayGetText$(value1)

let s$ = displayGetText$(5);

displayInit(value1, value2)

retVal = displayInit(1, 2);

SD Card and MP3

sdInit()

retVal = sdInit();

sdDeinit()

retVal = sdDeinit();

sdMounted()

retVal = sdMounted();

sdExists(text1$)

retVal = sdExists("/sdcard/test.txt");

sdFileSize(text1$)

retVal = sdFileSize("/sdcard/test.txt");

sdWriteText(text1$, text2$)

retVal = sdWriteText("/sdcard/test.txt", "Hello B9X");

sdAppendText(text1$, text2$)

retVal = sdAppendText("/sdcard/test.txt", "More text");

sdDelete(text1$)

retVal = sdDelete("/sdcard/test.txt");

sdRename(text1$, text2$)

retVal = sdRename("/sdcard/old.txt", "/sdcard/new.txt");

sdMakeDir(text1$)

retVal = sdMakeDir("/sdcard/data");

mp3Play(text1$)

retVal = mp3Play("/sdcard/music.mp3");

mp3Stop()

retVal = mp3Stop();

mp3Pause()

retVal = mp3Pause();

mp3Resume()

retVal = mp3Resume();

mp3IsPlaying()

retVal = mp3IsPlaying();

mp3SetVolume(value1)

retVal = mp3SetVolume(75);

mp3LastResult()

retVal = mp3LastResult();

sdReadText$(text1$)

let s$ = sdReadText$("/sdcard/test.txt");

sdList$(text1$)

let s$ = sdList$("/sdcard");

sdFindFirst$(text1$)

let s$ = sdFindFirst$("/sdcard/*.mp3");

sdFindNext$()

let s$ = sdFindNext$();

sdFindPrevious$()

let s$ = sdFindPrevious$();

mp3LastError$()

let s$ = mp3LastError$();

VoIP and Audio

play(text1$)

retVal = play("value");

voipInit(value1, value2, value3, value4, value5, value6)

retVal = voipInit(1, 2, 3, 4, 5, 6);

voipConnect(text1$, value2, text3$, text4$, text5$)

retVal = voipConnect("value", 2, "text", "text", "text");

voipClose()

retVal = voipClose();

voipIsSending()

retVal = voipIsSending();

voipIsConnected()

retVal = voipIsConnected();

voipStartListening()

retVal = voipStartListening();

voipHaltListening()

retVal = voipHaltListening();

voipStartSending()

retVal = voipStartSending();

voipHaltSending()

retVal = voipHaltSending();

voipEnableVOX(value1)

retVal = voipEnableVOX(1);

voipDisableVOX()

retVal = voipDisableVOX();

voipIsVOXActive()

retVal = voipIsVOXActive();

voipSetVolume(value1)

retVal = voipSetVolume(1);

voipSetMicGain(value1)

retVal = voipSetMicGain(1);

playInit(value1, value2, value3)

retVal = playInit(1, 2, 3);

isPlaying()

retVal = isPlaying();

Online AI, TTS and Voice

ttsSpeak(text1$)

retVal = ttsSpeak("Hello from B9X");

ttsxInit(value1, value2, value3, text4$, text5$, text6$)

retVal = ttsxInit(1, 2, 3, "text", "text", "text");

ttsxSpeak(text1$)

retVal = ttsxSpeak("Hello from B9X");

vrxInit(value1, value2, value3, value4, text5$)

retVal = vrxInit(1, 2, 3, 4, "text");

vrxTranscribe(value1)

retVal = vrxTranscribe(1);

oaixInit(text1$)

retVal = oaixInit("YOUR_API_KEY");

oaixAskQuestion(value1, text2$)

retVal = oaixAskQuestion(1, "text");

vrxGetTranscript$()

let s$ = vrxGetTranscript$();

oaixGetAnswer$()

let s$ = oaixGetAnswer$();

ttsInit(value1, value2, value3, value4)

retVal = ttsInit(1, 2, 3, 4);

ttsIsBusy()

retVal = ttsIsBusy();

MQTT

mqttClientUnsubscribe(text1$)

retVal = mqttClientUnsubscribe("b9x/status");

mqttClientSubscribe(text1$)

retVal = mqttClientSubscribe("b9x/status");

mqttClientPublish(text1$, text2$)

retVal = mqttClientPublish("b9x/status", "online");

initMQTTClient(text1$, text2$, text3$)

retVal = initMQTTClient("broker-address", "username", "password");

mqttClientGetMessage$()

let s$ = mqttClientGetMessage$();

GPIO, ADC, Timing and Sensors

motionInit(value1, value2)

retVal = motionInit(1, 2);

motionGetDistance()

retVal = motionGetDistance();

wait(value1)

retVal = wait(100);

readTemperature(value1)

retVal = readTemperature(4);

initADC()

retVal = initADC();

readADCMV(value1)

retVal = readADCMV(0);

readADCRaw(value1)

retVal = readADCRaw(0);

deinitADC()

retVal = deinitADC();

makeInput(value1)

retVal = makeInput(4);

getInput(value1)

retVal = getInput(4);

makeOutput(value1)

retVal = makeOutput(2);

setHigh(value1)

retVal = setHigh(2);

setLow(value1)

retVal = setLow(2);

getTicks(value1)

retVal = getTicks(1);

Infrared and WS2812

irInit(value1)

retVal = irInit(4);

irGetCode()

retVal = irGetCode();

ws2812Init(value1, value2)

retVal = ws2812Init(1, 2);

ws2812Fill(value1, value2, value3, value4)

retVal = ws2812Fill(1, 2, 3, 4);

ws2812SetPixel(value1, value2, value3, value4, value5)

retVal = ws2812SetPixel(1, 2, 3, 4, 5);

ws2812Show(value1)

retVal = ws2812Show(1);

ws2812Clear(value1)

retVal = ws2812Clear(1);

ws2812IsBusy(value1)

retVal = ws2812IsBusy(1);

Storage, System and Network

setNVS(text1$, text2$)

retVal = setNVS("ssid", "MyNetwork");

logData(text1$, text2$)

retVal = logData("value", "text");

getNVS$(text1$)

let s$ = getNVS$("ssid");

memx()

retVal = memx();

wifiIsConnected()

retVal = wifiIsConnected();

getResetType()

retVal = getResetType();

restart()

retVal = restart();

Math, Formatting and Date/Time

fmt$(value1, text2$)

let s$ = fmt$(1234.5, "#,##0.00");

hour()

retVal = hour();

minute()

retVal = minute();

second()

retVal = second();

month()

retVal = month();

day()

retVal = day();

year()

retVal = year();

weekDay()

retVal = weekDay();

abs(value1)

retVal = abs(-12.5);

log(value1)

retVal = log(10);

log10(value1)

retVal = log10(100);

round(value1)

retVal = round(12.6);

exp(value1)

retVal = exp(2);

sin(value1)

retVal = sin(1);

cos(value1)

retVal = cos(1);

tan(value1)

retVal = tan(1);

asin(value1)

retVal = asin(0.5);

acos(value1)

retVal = acos(0.5);

atan(value1)

retVal = atan(1);

sinh(value1)

retVal = sinh(1);

cosh(value1)

retVal = cosh(1);

rnd(value1, value2)

retVal = rnd(1, 10);

sqrt(value1)

retVal = sqrt(81);

modulo(value1, value2)

retVal = modulo(10, 3);

min(value1, value2)

retVal = min(10, 20);

max(value1, value2)

retVal = max(10, 20);

Built-in icon gallery

The B9X Basic GUI Module includes the following built-in icons. The number shown beside each image is the iconNumber used with displayAddIcon() and displaySetIcon().

result = displayAddIcon(14, 111, 309, 17);  ' icon 17 = Play
result = displaySetIcon(14, 18);            ' change to Pause

Icon number reference

8. GUI event messages

getDisplayMessage$() returns the next queued GUI event. When no event is waiting it returns an empty string.

[DMSG][elementNumber][elementType][activity][value][x][y][text]

The GUI uses portrait 320 × 480 coordinates. Element numbers should be unique among active elements. Up to 48 active GUI elements are supported. GUI colors use numeric RGB565 values.

9. Programming patterns

Basic GUI application

START_BUTTON = 1;
STATUS_LABEL = 2;
LEVEL_SLIDER = 3;

result = displayRemoveAllElements();
result = displayClear(0);

result = displayAddButton(START_BUTTON, 20, 40, 130, 45, "START", 2);
result = displayAddLabel(STATUS_LABEL, 20, 100, 280, 35, "Ready", 2, 65535);
result = displayAddSlider(LEVEL_SLIDER, 10, 170, 298, 51, 0, 100, 50);
result = displayRefresh();

while 1 do
    let msg$ = getDisplayMessage$();
    if len(msg$) > 0 then
        print msg$;
    endif
    wait(10);
wend

Editable text and password

result = displayAddTextBox(10, 20, 60, 280, 42, "", 32, 2);
result = displayAddPasswordTextBox(11, 20, 120, 280, 42, "", 32, 2);
result = displayAddKeyboard(30, 10);
result = displayRefresh();

let user$ = displayGetText$(10);
let password$ = displayGetText$(11);

MQTT

result = initMQTTClient("broker-address", "username", "password");
result = mqttClientSubscribe("b9x/status");
result = mqttClientPublish("b9x/status", "online");

let mqttMessage$ = mqttClientGetMessage$();

SD text file

result = sdInit();
result = sdWriteText("/sdcard/test.txt", "B9X Basic");
let text$ = sdReadText$("/sdcard/test.txt");
print text$;

10. Language limits and quick reference

Reserved/control words used by the language

LET, PRINT, DIM, IF, THEN, ELSE, ENDIF, WHILE, DO, WEND, FOR, TO, STEP, NEXT, SUB, END SUB, CALL, FUNCTION, END FUNCTION, RETURN, AND, OR, NOT.

B9X Basic GUI Module • B9X Electronics • Copyright © 2026 B9X Electronics. All Rights Reserved.