maehw / webpbrick

Web-based IDE for programming the LEGO Mindstorms RCX using NQC with modern technologies

README

This git repository provides the source codes for the WebPBrick project and hence the webpbrick.com website.

WebPBrick How To

1. Write NQC code (or use BlockNQC to generate the code)
2. Build your NQC code (click the "Build" button)
3. Connect to the yellow programmable RCX brick using an infrared tower (click the "Serial Connect" button)
4. Download your compiled program to the RCX (click the "Download program to RCX" button)

WebPBrick's BlockNQC

A web-based visual programming editor called BlockNQC can be used to generate NQC code. BlockNQC is based on Google's Blockly. For details, see BlockNQC's separate README file.

Toolchain modules

WebPBrick's toolchain consists of several modules:

• BlockNQC: Web-based visual programming editor called BlockNQC that can be used to generate NQC code (based on Google's Blockly).
• WebNQC: The NQC compiler built as WebAssembly (WASM) for the web using emscripten.
• RCX image parser written in Kaitai Struct and compiled to JavaScript to parse and split RCX image binary files so that they can be downloaded to the RCX in their bytecode chunks.
• RCX communication libraries:
  • Based on Web Serial API to be used with the LEGO IR Serial Tower and DIY IR serial towers
  • Based on WebUSB API to be used with LEGO IR USB Tower

Those modules could be used independently.

Run

Start a local webserver, e.g. using Python:

python -m http.server 8080

Open your web browser and navigate to http://localhost:8080/ide/

Licenses

This project is a collection of modules and open source software.

Module	License
NQC / WebNQC	Mozilla Public License 2.0
NQC example code by D. Baum and R. Zurcher	Freeware License
Blockly (required for BlockNQC)	Apache License 2.0
all others WebPBrick modules (e.g. BlockNQC and the IDE)	GNU GPLv3

Released versions

Please find the CHANGELOG here. Please also note that WebPbrick.com may not be up-to-date with this repository on GitHub.

Disclaimer

LEGO® is a trademark of the LEGO Group of companies which does not sponsor, authorize or endorse this project.

webpbrick's Issues

Disconnect before trying to connect again after a failed serial connection attempt

Describe the bug

Need to disconnect before trying to connect again after a failed serial connection attempt.

To Reproduce

Steps to reproduce the behavior:

1. Switch RCX off or put out of line of sight from the IR tower.
2. Press the "Serial Connect" button
3. See the error message "Connected to serial device (baudrate: 2400).
   ❌️ No communication with RCX possible.
   RCX needs to be switched on and placed close to and in line of sight of the IR tower."
4. Need to press "Serial Disconnect" and then "Serial Connect" again after having switched the RCX on or in line of sight.

Expected behavior

The IDE knows when a connection attempt has failed and could

1. Close the serial connection.
2. Re-label the connection button to "Serial Connect"
   without requiring the user to press the button twice.

Even better would be to leave the serial connection open (the serial device will be the same) and re-attempt the communication ping with the RCX.

Screenshots

Operating system & webbrowser:

Considered irrelevant.

RCX hardware & firmware:

Considered irrelevant.

Additional context

Only involves changing JavaScript code and no deep insights into how the serial communication between IR tower and RCX works.

Select what firmware to download

Is your feature request related to a problem? Please describe.

Currently, there's only one firmware that can be downloaded to the yellow programmable brick (the RCX). The user may blindly download the firmware without knowing what it was specifically. - Which is probably OK für 95% of the user base.

FYI: It's firm0328.lgo, i.e. LEGO's official firmware version 3.28.

There's other firmware available, see https://pbrick.info/index.html-p=74.html
Not only other official versions (3.09 and 3.32) but also from Dick Swan and alternative firmwares to be used with leJOS, pbFORTH and legOS BrickOS. Probably even others - if we can still find them in the WWW of this MINDSTORMS legacy.

Describe the solution you'd like

I'd like to have a selection dialog for the firmware. LEGO's 3.32 official firmware should probably the default so that no background knowledge is required. Choosing another firmware could be an advanced feature which is not directly visible ("expert mode") so that user's can't to something "wrong" (unintended).

Describe alternatives you've considered

Make the firmware files available and let the very advanced user use their web browser development console, add breakpoints to the JavaScript code and manually select the correct firmware from their. Doesn't feel very user-friendly though...

Additional context

Different firmwares are used for different RCX hardware revisions - or different alternative programming languages and their environments (e.g. pbFORTH, BrickOS, etc).

Expose RuntimeErrors to the user, e.g. integer divide by zero

Is your feature request related to a problem? Please describe.
User is unable to see why their code does not compile even though there's an error message covered under the hood.

I've discovered this by having a division by zero in my NQC code (more or less intentional). The minimal example to reproduce this in WebPBrick v0.1.0:

int x;


task main() {
  x = 1 / 0;
}

The web development console logs:

Uncaught (in promise) RuntimeError: integer divide by zero
    createWebNqc https://webpbrick.com/nqc/webnqc/nqc.js:711
    callMain https://webpbrick.com/nqc/webnqc/nqc.js:4951
    clickConvert https://webpbrick.com/ide/nqcWrapper.js:179

Describe the solution you'd like
Uncover the hidden error message and "expose" it to the user by displaying it in the usual log area.

Describe alternatives you've considered
Let the advance user find this out theirselves... (not a real alternative from my POV).

Additional context
N/A

Indicate required build before program download

Describe the bug

Not really a bug, but a potential user experience (UX) improvement.

To Reproduce

1. Write NQC code
2. Press the "Build" button
3. Press the "Download program to RCX" button
4. Play around with user program on the RCX
5. Modify code
6. Press the "Download program to RCX" button
7. Play around with user program on the RCX
8. Wonder why code changes do not have any effects

Expected behavior

When downloading, the user could be informed that they made changes to the code that have not been compiled and hence the built binary may not include the expected changes.

Alternatively, we could combine the build step into a "Build & download" step as there's probably only a very small majority of users who only want to build their code - and maybe expect the binary.

Screenshots

N/A

Operating system & webbrowser:

Considered irrelevant here.

RCX hardware & firmware:

Considered irrelevant here.

Additional context

There may be users with web browsers that only support WebAssembly (WASM) but not Web Serial or WebUSB APIs and therefore only play around with writing NQC code and compiling it, i.e. press the "Build" button and want to see what happens.

(EDIT) Suggestion: Replace the two buttons ("🧱 Build" and "⬇️ Download program to RCX") with a "universal" button.
Dependent on web browser capabilities, label that button and use different functionalities. Only WASM available? Stick with "🧱 Build" as no IR communication is available for download. WASM + WebSerial available? Then re-label the button "🧱 Build + ⬇️ Download program to RCX" and have both functionalities executed after each other automatically.