1. Language fundamentals

B9X Basic is a compact embedded language. Programs contain executable statements and optional SUB and FUNCTION definitions. Simple statements end with a semicolon. Block endings such as ENDIF, WEND, NEXT, END SUB and END FUNCTION do not.

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

Comments

' Apostrophe comment
// C++-style comment
/* Block comment
   across lines */

2. Values, variables and arrays

All ordinary numeric variables and numeric function results are double-precision values. String names end in $, hold up to 512 characters and require LET when assigned.

temperature = 72.5;
let title$ = "B9X Basic";

dim samples[9];       ' indices 0 through 9
samples[0] = 12.5;
retval = samples[0];

The declared array bound is inclusive. String arrays are not implemented. Variables created outside a function are global. Function parameters temporarily hold local argument values and are restored when the function returns. A function can still read or modify other global variables.

3. Expressions and operators

result = 2 + 3 * 4;
power = 2 ** 3 ** 2;
enabled = temperature >= 25 and alarm == 1;
let message$ = "Value: " + str$(result);

Use == for comparison. A single = performs assignment.

4. Statements and control flow

if temperature > 80 then
    print "High";
else
    print "Normal";
endif

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

for i = 0 to 10 step 2 do
    print i;
next

STEP defaults to 1 and may be negative. Do not use zero. Braces may form an explicit statement block. B9X Basic does not implement line numbers, GOTO, GOSUB, INPUT, DATA/READ, SELECT CASE, BREAK or CONTINUE.

5. Subroutines and user functions

SUB

A SUB is an argument-free procedure invoked with CALL. It may use RETURN; to exit early.

sub blink()
    retval = setHigh(2);
    retval = wait(100);
    retval = 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

retval = clamp(120, 0, 100);

String FUNCTION

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

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

A user function accepts up to eight numeric or string parameters. String parameter and function names end in $. Define a function before the code that calls it.

6. Core string functions

retval = len("B9X");

let retstr$ = left$("B9X Basic", 3);

let retstr$ = right$("B9X Basic", 5);

let retstr$ = mid$("B9X Basic", 5, 5);

let retstr$ = chr$(65);

retval = asc("A");

let retstr$ = str$(12.5);

retval = val("12.5 volts");

retval = instr("B9X Basic", "Basic");
retval = instr(6, "banana", "a");

7. Formatting and time

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

8. Mathematics

All functions in this table return a double and therefore must be assigned.

9. System, Wi-Fi and nonvolatile storage

retval = wifiIsConnected();

retval = memx();

retval = setNVS("station", "workbench");

let retstr$ = getNVS$("station");

10. GPIO, timing, ADC and temperature

11. Display, motion, WAV and local TTS

WAV playback supports uncompressed 44.1 kHz, 16-bit stereo PCM WAV files.

12. OpenAI text, transcription and TTS

Answer and transcript polling functions return an empty string while no result is ready. A 401 response normally means the API key is invalid.

13. B9X Voice Server VoIP

retval = voipInit(15, 16, 17, 4, 5, 6);

let server$ = "192.168.1.100";
serverPort = 18000;
let password$ = "serverPassword";
let nodeName$ = "Workshop ESP32";
let encryptionKey$ = b9x_key2$;

retval = voipConnect(server$, serverPort, password$, nodeName$, encryptionKey$);

retval = voipIsConnected();

retval = voipStartListening();

retval = voipHaltListening();

retval = voipStartSending();

retval = voipHaltSending();

retval = voipIsSending();

retval = voipClose();

Complete push-to-talk pattern

retval = voipInit(15, 16, 17, 4, 5, 6);
retval = voipConnect("192.168.1.100", 18000, "password", "B9X Node", b9x_key2$);

' Wait for asynchronous connection
connected = 0;
while connected == 0 do
    connected = voipIsConnected();
    retval = wait(100);
wend

' Listen initially
retval = voipStartListening();

' Begin push-to-talk
retval = voipHaltListening();
retval = voipStartSending();

' End push-to-talk
retval = voipHaltSending();
retval = voipStartListening();

14. Infrared remote control

retval = irInit(15);

retval = irGetCode();

15. WS2812 addressable LEDs

Color-changing functions return 0 on success or an error code. ws2812IsBusy returns nonzero while transmission is active.

16. MQTT

Numeric operations return a message identifier or error value. The polling function returns an empty string when nothing is ready, otherwise [TYPE][id][topic][data]. Event types include DATA, CONNECT, DISCONNECT, SUBSCRIBED, UNSUBSCRIBED, PUBLISHED and ERROR.

17. File logging and reset information

retval = logData("data.csv", "72.5,Running");

retval = getResetType();

retval = restart();

18. Supplied user-function templates

These functions demonstrate adding native C functions with numeric, string and mixed argument types.

19. Protected key variables

B9X Basic supplies five protected string variables for passwords, API keys and encryption keys:

b9x_key1$
b9x_key2$
b9x_key3$
b9x_key4$
b9x_key5$

Each holds up to 512 characters and can be passed to OpenAI, MQTT, NVS or VoIP functions. Values may be updated through the setup menu without displaying the current value. For B9X Voice Server, store the 32-character AES key in one protected variable instead of embedding it in a shared BASIC program.

20. Complete programming patterns

Safe polling pattern

retval = oaixInit(b9x_key1$);
retval = oaixAskQuestion(1, "Give one short electronics fact.");
let answer$ = "";

answerLength = len(answer$);
while answerLength == 0 do
    let answer$ = oaixGetAnswer$();
    retval = wait(50);
    answerLength = len(answer$);
wend

print answer$;

GPIO debounce

retval = makeInput(4);
last = getInput(4);

while 1 do
    current = getInput(4);
    if current != last then
        retval = wait(20);
        current = getInput(4);
        if current != last then
            print current;
            last = current;
        endif
    endif
    retval = wait(5);
wend

Common mistakes

Appendix: limits and quick reference

' Numeric assignment
name = expression;
let name = expression;

' String assignment
let name$ = string_expression;

' Function results
retval = numericFunction(arguments);
let retstr$ = stringFunction$(arguments);

' Array
dim values[9];
values[index] = expression;

' Control flow
if expression then ... else ... endif
while expression do ... wend
for name = start to limit step amount do ... next

' Procedures and functions
sub name() ... end sub
call name();
function name(parameters) ... return expression; ... end function
function name$(parameters) ... return string_expression; ... end function

Return to top ↑