Migrating to vs Code

docs/contributing/translating.md

@@ -1,6 +1,7 @@
 ---
 title: Translating Wokwi
 sidebar_label: Translating
+description: Contribute translations for Wokwi so even more people can enjoy using it!
 ---
 
 This page explains how you can contribute translations to Wokwi.

docs/vscode/migrating.md

@@ -0,0 +1,176 @@
+---
+title: Migrating Wokwi projects to VS Code
+sidebar_label: Migrating to VS Code
+description:  Migrate your online Wokwi simulator projects to a local VS Code environment
+keywords: [Visual Studio Code, VS Code, embedded simulation, IoT simulation, PlatformIO, ESP-IDF, Arduino, MicroPython, Rust, Zephyr]
+---
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The web-based Wokwi simulator is a powerful and well-integrated way to try out your project designs: there are many capabilities which "just work" in the online simulator which will require some additional steps or workarounds to build and run locally.
+
+This checklist of steps should help you overcome the most common issues. It is assumed that you have already installed the VS Code extension for Wokwi (see the [Getting started guide](./getting-started)).
+
+:::tip
+
+Using **MicroPython**? The setup for MicroPython projects is quite different - please see the [Vs Code for MicroPython page](vscode-micropython.md).
+:::
+
+## Download the project source
+
+To start, the first step is to save your online project. From the same menu, under the save button, you can then select to download a `.zip` archive of the project. This will contain useful files such as any source code and the `diagram.json` file used by Wokwi.
+Once downloaded you can extract the files from the archive and use them in your local project.
+
+## Create an empty project in VS Code
+
+If you are using an extension such as ESP-IDF or PlatformIO in VS Code, it is far easier to create an empty template project first before adding your Wokwi code. Use the provided templates for your chosen platform to create a new empty project. This will include specifying the hardware to be targeted and will create the required source structure and build files.
+
+This step will create a boilerplate project in a working state, ready to add your own code.
+
+## Add the source
+
+Depending on the complexity of your project, adding the source should be quite straightforward.
+
+<Tabs>
+  <TabItem value="pio" label="PlatformIO" default>
+
+    For a new PlatformIO Arduino project, the directory tree should look like this:
+
+    ```text
+    ├── .gitignore
+    ├── include
+    │   └── README
+    ├── lib
+    │   └── README
+    ├── .pio
+    │   └── build
+    │       ├── project.checksum
+    │       └── uno
+    │           └── idedata.json
+    ├── platformio.ini
+    ├── src
+    │   └── main.cpp
+    ├── test
+    │   └── README
+
+    ```
+
+    In this case you would delete the `/src/main.cpp`  and replace it with the '.ino' file from the project you downloaded.
+
+    :::tip
+
+    PlatformIO encourages the use of standard C++ files (`.cpp`). To convert your `.ino` file, you can rename it and change the extension to '.cpp', but you will also need to add a line to include the standard Arduino headers at the beginning of the file:
+    ```
+    #include <Arduino.h>
+    ```
+    Any user functions should also be declared before they are called. There is a more detailed example of this in the [PlatformIO documentation FAQ](https://docs.platformio.org/en/latest/faq/ino-to-cpp.html).
+
+    :::
+  </TabItem>
+  <TabItem value="ESP-IDF" label="ESP-IDF">
+    For ESP-IDF the default project directory tree looks like this:
+
+    ```text
+    ├── build
+    │   ├── app-flash_args
+    │   ├── bootloader
+    │   ├── bootloader-flash_args
+    │   ├── bootloader-prefix
+    |   ...
+    │   ├── cmake_install.cmake
+    │   ├── compile_commands.json
+    │   ├── config
+    │   │   ├── kconfig_menus.json
+    │   │   ├── sdkconfig.cmake
+    │   │   ├── sdkconfig.h
+    │   │   └── sdkconfig.json
+    │   ├── config.env
+    │   ├── esp-idf
+    │   ...
+    ├── CMakeLists.txt
+    ├── main
+    │   ├── CMakeLists.txt
+    │   └── main.c
+    ├── README.md
+    └── sdkconfig
+    ```
+    :::note
+    This is not the entire tree, as it is very large!
+    :::
+
+    The `build` directory is where the built artifacts will be created, which you will need to refer to in a later step.
+
+    All of the source files should go in `main.c`. If you have multiple source files, you should also update the `CMakelists.txt` file in the same directory to include any other files which need to be built.
+
+  </TabItem>
+  <TabItem value="Zephyr" label="Zephyr">
+
+  </TabItem>
+</Tabs>  
+
+
+## Verify/add libraries
+
+If your project has used any additional libraries you may need to resolve them for your local build environment. The Wokwi online simulator includes access to a whole range of built-in and third party libraries which you may have added to your project - now your local build environment will also need them. It is usually better to use the library manager included with your build tools to ensure that you get an up to date and known working version of the library.
+
+<Tabs>
+  <TabItem value="pio" label="PlatformIO" default>
+    If you are using PlatformIO in VS Code, many libraries are available in the Library Manager. Use the `libraries.txt` file downloaded with your project as a guide to the names of the libraries you need.
+
+    The PlatformIO Library Manager has a search facility which will make this easier - just copy in the name of the library and hit search. Clicking on the 'Add' button will add the library to the `platformio.ini` file for each of the build targets you have configured.
+
+    ![PlatformIO Library Manager](./images/pio-library.png)
+
+    Note that many libraries have similar or sometimes even the same name.
+
+  </TabItem>
+  <TabItem value="ESP-IDF" label="ESP-IDF">
+    If you are using the ESP-IDF extension for VS Code, libraries are managed as 'components'. A component is any modular code object compiled as a static library. The component library for ESP-IDF, much like the Library Manager in PlatformIO, contains many useful libraries maintained by Espressif, and tested third-party contributions.
+
+    ![ESP-IDF Component Manager](./images/component.png)
+
+  </TabItem>
+  <TabItem value="Manual" label="Custom libraries">
+    If the library you wish to use isn't available in the supported available libraries, you can add it manually. 
+
+    For PlatformIO, the [library documentation](https://docs.platformio.org/en/latest/librarymanager/creating.html) will give further guidance.
+
+    For ESP-IDF projects, custom libraries can be added as a component. Check out the [ESP-IDF project structure documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#example-project) for more details.
+  </TabItem>
+</Tabs>
+
+## Test the build tools
+
+The Wokwi simulator requires a built firmware file to run, so the next step should be to check that you can generate one. Use the relevant build command from your chosen framework to build the files.
+
+Check the terminal window output for any errors or warnings which you may want or need to correct.
+
+![PlatformIO build success](images/build.png)
+
+## Add configuration
+
+The online simulator controls its own build environment. To work locally in VS Code, you will need to provide an extra configuration file, `wokwi.toml`. This will not be part of the downloaded archive because Wokwi doesn't know what build tools or framework you will use for local VS Code development.
+
+The structure and contents of the `wokwi.toml` file are covered in the [VS Code project configuration page](/vscode/project-config). In the previous step you already built the firmware files needed.
+
+:::tip
+
+You can also generate the `wokwi.toml` file using the Wokwi CLI if it is installed (see [install instructions here](/wokwi-ci/cli-installation)), by running the command:
+
+```shell
+wokwi-cli init
+```
+:::
+
+
+At this point you should also add the `diagram.json` file from your downloaded project. This must be in the same directory as the `wokwi.toml` file.
+
+## Test the simulator
+
+When you select the `diagram.json` file in the VS Code editor, it will automatically open an embedded window with a graphical display showing the Wokwi circuit layout.
+
+![Wokwi diagram](./images/diagram.png)
+
+Use the start button in this window to start the simulation. The simulation should run exactly as it did in the online Wokwi simulator.
+
+Note: You will need a license to edit the diagram in this view ([see the Wokwi pricing page](https://wokwi.com/pricing?ref=docs_migrating)).

docs/vscode/offline-mode.md

@@ -9,7 +9,7 @@ Wokwi for VS Code requires an internet connection to run. If you need to use Wok
 
 When running in offline mode, the title of the simulator tab will be "Wokwi Simulator (Offline)", and the simulator will display the date when the simulation engine was last updated:
 
-![Wokwi Simulator (Offline)](./offline-mode.png)
+![Wokwi Simulator (Offline)](./images/offline-mode.png)
 
 To update the simulator engine, go online and start the simulator. The simulator will automatically update the engine to the latest version, and will use it the next time you run the simulator in offline mode.
 

docs/vscode/vscode-micropython.md

@@ -0,0 +1,118 @@
+---
+title: MicroPython projects in VS Code
+sidebar_label: MicroPython in VS Code
+description:  Migrate or create MicroPython projects incorporating the Wokwi simulator in a local VS Code environment
+keywords: [Visual Studio Code, VS Code, embedded simulation, IoT simulation, MicroPython]
+---
+
+MicroPython projects differ from those in most of the other frameworks, because in this case the majority of the firmware to be installed on your hardware device (or Wokwi simulator) is MicroPython itself. This firmware, the `main.py` you create and any additional libraries are the components which need to be uploaded.
+When the device or simulator is initialized or rebooted, it will first load MicroPython, then run the `main.py` code, and then (assuming the main code exits) respond to further interaction using the [REPL](https://docs.micropython.org/en/latest/esp8266/tutorial/repl.html) prompt.
+In the case of the Wokwi simulator, this means, in addition to the code you have created, it also requires a version of the firmware to run the simulation on.
+
+## Before you start
+
+There are three things you should install before migrating your project to VS Code (or starting a new one).
+
+1. Make sure you have the VS Code extension for Wokwi (See the [getting started guide](./getting-started#installation)).
+1. Install the **mpremote** software (see the [MicroPython documentation](https://docs.micropython.org/en/latest/reference/mpremote.html) for this step). This software uses a serial connection to your MicroPython-enabled hardware (or the Wokwi simulator) to manage the filesystem and perform tasks such as rebooting or entering the REPL interactive mode.
+   :::warning
+   To avoid compatibility issues, it is strongly advised to install **a version of mpremote of the same version as your firmware**. The default firmware in the project repository is currently `1.23`. To install the matching mpremote with `pip` for example:
+
+   ```bash
+   pip install mpremote==1.23
+   ```
+
+   ...or adjust for whatever method you are using for installing `mpremote`.
+   :::
+1. Clone the [example project from GitHub](https://github.com/wokwi/wokwi-vscode-micropython). This project has been set up with the relevant files that the Wokwi simulator requires for different types of hardware. You can visit the link to clone or download the repository, or [download it via this link](https://github.com/wokwi/wokwi-vscode-micropython/archive/refs/heads/main.zip) as a zip file. Remember to uncompress the file somewhere you want to work with it!
+
+## Open the repository in Visual Studio Code
+
+Run Visual Studio Code and then use 'File>Open folder' to open the directory containing the example project.
+You'll find the project contains a useful README, a `main.py` file and some hardware specific directories (`esp32`, `rp2040`, and so on, for different microcontrollers).
+
+![Screenshot showing the VS Code directory structure](./images/vs-micropython-01.png)
+
+Each of the hardware directories contains the relevant firmware file for MicroPython, a Wokwi `diagram.json` file and the `wokwi.toml` file used to configure the simulator.
+
+Select the `diagram.json` file, and a new view should open showing a board and the familiar Wokwi simulation display. Click on the play button to run the simulation and test that it works.
+
+![Running the demo code](./images/vs-micropython-02.png)
+
+Once the simulator starts, it will also open a terminal window which will show the startup messages and then start the interactive REPL. You can enter MicroPython commands here to further test the simulation.
+
+What you may have noticed is that it didn't execute the code in `main.py`. That's because the local version of `main.py` hasn't been uploaded to the filesystem of MicroPython in the simulator - it's just running the bare MicroPython firmware.
+
+## (Optional) Add your own files
+
+If you have downloaded a MicroPython project from the Wokwi online simulator, you should add these files to the project, replacing the default files. The download will contain at a minimum the `main.py` file and a `diagram.json` file.
+
+Replace `main.py` in the main directory of the project with your own. If you used any additional files (for example, extra python modules or data files), these should also be added here.
+
+The `diagram.json` file needs to be in the hardware specific directories. Copy it into each of the hardware directories (or just the ones you intend to use).
+
+You can select the `diagram.json` file again to open the simulator and confirm that your circuit is displayed.
+
+## Uploading files to the Wokwi simulator
+
+Before we can upload anything, we need to start the simulation. When it's running, Wokwi also opens a serial connection through a server on a local port. We can then use this connection to upload the files.
+
+:::note
+The serial port configuration for the simulator can be found in the `wokwi.toml` file in eache hardware specific directory:
+```
+rfc2217ServerPort = 4000
+```
+This designates port '4000' for the connection. You may wish to change this if you have other services already using this port.  
+:::
+
+To upload the `main.py` file, open a new terminal (you can add an additional terminal within VS Code and switch between it and the Wokwi REPL) and enter the command to upload the `main.py` file:
+
+```
+mpremote connect port:rfc2217://localhost:4000 fs cp main.py :main.py 
+```
+
+:::note
+Sometimes the command will return an error which ends with `TransportError("could not enter raw repl")`. If you get this error you can force the REPL into 'Raw' mode by activating the Wokwi REPL window and pressing <kbd>Ctrl</kbd> + <kbd>A</kbd>, then go back to your terminal and run the command again.
+:::
+
+:::tip
+On Unix based systems (e.g. Mac or Linux), you can create a shortcut for connecting to the simulator by running the following command:
+```
+mkdir -p ~/.config/mpremote
+echo 'config={"wokwi": "connect port:rfc2217://localhost:4000"}' > ~/.config/mpremote/config.py
+```
+After running this command, you can connect to the simulator by running `mpremote wokwi`.
+:::
+
+You can also use `mpremote` to install libraries which are part of the MicroPython `mip` package library. For example, to install the `ssd1306` library:
+
+```
+mpremote connect port:rfc2217://localhost:4000 mip install ssd1306
+```
+
+For your own additional files, simply upload with the syntax:
+
+```
+mpremote connect port:rfc2217://localhost:4000 fs cp <filename> :<filename>
+```
+
+You can confirm what files have been uploaded with the `ls` command:
+
+```
+ mpremote connect port:rfc2217://localhost:4000 ls
+```
+
+Once the required files are uploaded, activate the Wokwi REPL again and enter the following:
+
+```python
+import machine
+machine.reset()
+```
+
+This will perform a hard reboot of the simulation and automatically run the `main.py` file.
+
+![Automatically running the main.py code on reset](./images/vs-micropython-03.png)
+
+:::warning
+The filesystem stored in the simulator is not persistent. If you stop the simulation or close the simulation window in VS Code, you will need to repeat the steps to upload any files or libraries again.
+:::

sidebars.js

@@ -92,6 +92,8 @@ module.exports = {
       'vscode/diagram-editor',
       'vscode/debugging',
       'vscode/offline-mode',
+      'vscode/migrating',
+      'vscode/vscode-micropython',
     ],
     'Wokwi CI': [
       'wokwi-ci/getting-started',