DocsOpen the editorEditor

VS Code and GitHub with Mokxi

Keep your projects in your own GitHub repository, edit the code in VS Code, and run it in Mokxi.

There are three ways to work with a project outside the browser, and they all use the same files, so you can mix them: save to GitHub from the editor, clone the repository and open it in VS Code, sync from VS Code or the terminal, and open it in Mokxi again.

What a saved project looks like

Every save to GitHub, every mokxi pull and every project VS Code opens has the same layout:

File What it is
Blink/Blink.ino the sketch, as an Arduino IDE folder, with its other tabs beside it
diagram.mokxi.json the whole project: parts, wires, notes and code. Mokxi opens it as it is
README.md what the project is, with an Open in Mokxi badge
.vscode/extensions.json recommends the Mokxi extension when the folder opens in VS Code
.vscode/settings.json which Mokxi project the folder is
.vscode/tasks.json push, pull, run, compile and upload as VS Code tasks
.gitignore leaves out the command line's sync state and build output

The folder takes the project's name, so the Arduino IDE opens it as it is (File > Open > Blink/Blink.ino). A project with two boards gets a folder for each, such as Traffic_Lights_uno1/ and Traffic_Lights_esp1/.

Edit the sketch in the folder, not inside diagram.mokxi.json: when Mokxi reads the repository back, the folder wins. A tab you delete from the folder is deleted from the project, and a new file in it becomes a new tab.

The README, .gitignore and the .vscode files are yours once they exist: Mokxi writes them the first time and leaves your edits alone after that.

Save to GitHub from the editor

  1. Open Export in the editor's header.
  2. Under GitHub, press Connect GitHub. GitHub asks you to let Mokxi write to your public repositories. Tick Include private repositories first if you want private ones too.
  3. Back in the editor, open Export again and press Save to GitHub.
  4. Pick New repository (Mokxi names it after the project) or one of yours, write a commit message if you like, and press Save to GitHub.

You get a link to the commit on GitHub. Every later save is a new commit on the same branch. The line at the top of the card says where you are:

  • Synced with ada/blink (main): GitHub has exactly this project.
  • Changes not saved to ada/blink yet: you changed the project since.
  • ada/blink has newer commits: somebody pushed to the repository. Use Open from GitHub to get them.

Open from GitHub

Open Export and press Open from GitHub, then pick one of your repositories or paste any repository you can read (owner/name or a github.com link).

  • A repository saved from Mokxi opens as it was saved, with any edits made to the sketch folder on GitHub or in VS Code.
  • A plain Arduino sketch repository (a folder with an .ino file) opens too. Mokxi puts it on an Uno, or an ESP32 when the sketch includes WiFi. Change the board if it is meant for another one.

What was open before goes on the shelf first, as with Open JSON, so nothing is lost. The Open in Mokxi badge in a saved repository's README opens the project right away.

Connecting, and disconnecting

Mokxi asks GitHub for repository access only when you press Connect GitHub, never when you sign in. It is a separate permission from signing in with GitHub, and it works the same if you sign in with Google, Microsoft or email.

The access is stored encrypted with your account and used only when you press Save or Open. Nothing else in Mokxi reads it, and it is never sent to your browser.

To disconnect, go to Settings > GitHub on your account page and press Disconnect. Mokxi revokes its access at GitHub and deletes it. Closing your account does the same. You can also revoke it on GitHub, under Settings > Applications > Authorized OAuth Apps.

GitHub sync is not offered to students in a class or to children's accounts.

VS Code

Install Mokxi from the VS Code Marketplace (search for Mokxi in the Extensions view). A folder saved from Mokxi already recommends it.

  1. Click the Mokxi icon in the Activity Bar and press Sign In. Approve the short code in your browser, or paste a token from Settings > Developer.
  2. Your projects are listed in the sidebar. Click one to open it as a folder.
  3. Edit the sketch. .ino files get Arduino highlighting, and snippets such as sketch, blink, button and every.
  4. Press Sync (the cloud on the editor's title bar) to send it to Mokxi, or Run in the Simulator (the play button) to run it on Mokxi and watch the serial output in the Mokxi Serial panel.
  5. Open in Mokxi (the Mokxi item in the status bar) opens it in the simulator in your browser.

Sync refuses to overwrite work done in the browser since your last sync, and Pull refuses to throw away edits you have not synced. Each tells you why and lets you choose.

Compile and upload

Mokxi's servers do not compile sketches: the editor does, in your browser. In VS Code, Mokxi: Compile uses arduino-cli if you have it, with errors in the Problems panel, and Mokxi: Compile and Upload to Mokxi syncs, compiles and stores the build with the project, so the simulator runs exactly what you built. Without arduino-cli, press Run in the Mokxi editor once after syncing: the build it makes is kept with the project, and Run in the Simulator uses it.

The command line

The same things work from a terminal with npx @mokxi/cli. See The mokxi command line.

npx @mokxi/cli login
npx @mokxi/cli pull https://mokxi.com/p/abc123 blink
cd blink && git init
npx @mokxi/cli push
npx @mokxi/cli run --seconds 5

Which plans

GitHub sync, the VS Code extension and the command line are on every plan. Running a circuit from VS Code or the command line uses the API minutes your plan includes; the developers page lists them.