Wokwi for VS Code Offline mode enabler

This projects enables Wokwi Visual Studio Code extension Offline mode.

To do so, the following steps are needed, which are explained later:

1. Download the code
2. Patch the code
3. Create a bundle
4. Generate a license key
5. Block Wokwi Internet access
6. Install the license key
7. Install/update the offline add-on

main.py file from the main directory combines steps 1-4. Steps 5-7 have to be performed manually. Below is a description of these steps:

Download the code

Internet access is required. Changes may happen that prevent downloading. Fallback files are available in the repository.

On each launch, Wokwi attempts to receive or update offline engine version, which is said in documentation. This is performed by sending a HTTP request to https://wokwi.com/api/vscode/update-v2.

This program used to use the way mentioned above, but now x-wokwi-hash header returned by making a request to VS Code extension front-end is used instead, to remove the need of having Wokwi license obtained from the official website.

According to that hash, the URL of index.json file from the current version is found, and the contents of the file point to other files that need to be downloaded.

Patch the code

Since Wokwi licenses are cryptographically signed, the only way to force the extension to accept locally generated keys would be to replace the public key present in entry.js file with own key.

The task can be done with a text editor, however, since the file is big and may cause performance issues when opened, this task it done via automated patcher instead.

Create a bundle

The files that were downloaded, as well as the patched file, in the previous steps, are compressed into a bundle, that then can be installed via Wokwi interface. The bundle is saved as bundle.wpk.

Generate a license key

Now it should be possible to launch Wokwi extension offline, but it will still complain about lack of license.

Wokwi license structure is:

Cleartext part: u=userid&n=name&e=email&x=expiration&f=features&p=plan

followed by NULL character, followed by RSA digital signature.

Userid is only used in telemetry. Name is displayed in license activation message and is exported in a license file. If it doesn't have @ character, it is displayed in the main window. Email is exported in license file. Expiration date should be in YYYYMMDD format and should be exactly 8 digits. 99991231 is the maximum valid date. Features is a hexadecimal number that consists of binary flags:

1. 1 - Diagram editor (unused)
2. 2 - Pro (unused)
3. 4 - Offline
4. 8 - Classroom (unused)

Only "Offline" flag is actually used at the moment, to hide or display offline add-on information/installation interface. Plan can be "club", "hobby", "hobbyplus", "pro", "classroom" and "addon-offline". Anything else is treated as Community plan, which lacks Diagram Editor.

Block Wokwi Internet access

To prevent Wokwi extension from loading the most recent online version, which would reject the license, open VS Code settings as JSON ("Preferences: Open User Settings (JSON)" in the command palette), and add "wokwi.devlocal": true line inside the highest level curly brackets there.

Install the license key

In the command palette, select "Wokwi: Manually Enter License Key" and insert the key that was generated on the previous step.

Install/update the offline add-on

Click Wokwi simulator sidebar icon, and go to "View License Information", then "Install Offline Bundle" or "Update Offline Bundle from File" and select bundle.wpk file.