diff --git a/README.md b/README.md index 6574b81dd..91b1a810d 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,19 @@ Azure DevOps Board Badge -Make without limit! Device Simulator Express, a Microsoft Garage project, allows you to code microcontrollers without the hardware on hand! You can program your Circuit Playground Express (CPX) or your BBC micro:bit! Test and debug your code on the device simulator and see the same +Make without limit! Device Simulator Express, a Microsoft Garage project, allows you to code microcontrollers without the hardware on hand! You can program your Adafruit Circuit Playground Express (CPX) or your BBC micro:bit! Test and debug your code on the device simulator and see the same result when you plug in your actual microcontroller. Curious about the output of the device, the serial monitor allows you to observe the device output. -CircuitPlayground Express +## Devices we support: +- [**Adafruit Circuit Playground Express (CPX)**](#adafruit-circuit-playground-express-cpx-simulator) + + [CircuitPlayground Express](#adafruit-circuit-playground-express-cpx-simulator) + +- [**BBC micro:bit**](#bbc-microbit-simulator) + + [bbc micro:bit](#bbc-microbit-simulator) + ## Build Status @@ -26,10 +34,10 @@ You will be prompted to install the Python dependencies during the first use. - _**[Visual Studio Code](https://code.visualstudio.com/)**_ - _**[Node](https://nodejs.org/en/download/)**_ -- _**[Python 3.7+](https://www.python.org/downloads/)**_: Make sure you've added python and pip to your PATH in your environment variables. (1) +- _**[Python 3.7+](https://www.python.org/downloads/)**_: Make sure you've added Python and pip to your PATH in your environment variables. (1) - _**[Python VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)**_: This will be installed automatically from the marketplace when you install Device Simulator Express. -## Circuit Playground Express (CPX) Simulator +## Adafruit Circuit Playground Express (CPX) Simulator ### Features @@ -39,7 +47,7 @@ You will be prompted to install the Python dependencies during the first use. - Serial monitor (available on Windows and Mac only) - Output panel for the simulator - Deploy CircuitPython code to the physical device. -- Simulation of the Adafruit Circuit Playground Express device, including: +- Simulation of the CPX device, including: - Green LED - Red LED - Push Buttons A and B @@ -74,70 +82,72 @@ As we only support CPX library now, other libraries (i.e. simpleio) can’t run To use Device Simulator Express, install the extension from the marketplace and reload VS Code. -#### 1. Start with the "Device Simulator Express [Circuit Playground Express]: New File" Command. +#### I. Take a look at the "Device Simulator Express: Getting Started" Command. +1. Type in `"Device Simulator Express: [Circuit Playground Express] New File"` in the command palette (`CTRL + SHIFT + P` / `CMD + SHIFT + P` to open the command palette). +Deploy to Device +1. Choose the `CPX` option from the dropdown. +2. Read, copy and learn some of the things you can do with the simulator! -1. Type in `"Device Simulator Express: [Circuit Playground Express] New File"` in the command palette (`CTRL+SHIFT+P` to open the command palette). - "New File" animation -2. Name and save your file somewhere, and we’re good to go! (3) -3. Start with some examples: you can find examples files and tutorials inside the comments, as well as in the notification pop up when you run the `"Device Simulator Express: [Circuit Playground Express] New File"` Command. +#### II. Start with the "Device Simulator Express [Circuit Playground Express]: New File" Command. -How to find example code screenshot +1. Type in `"Device Simulator Express: [Circuit Playground Express] New File"` in the command palette (`CTRL + SHIFT + P` / `CMD + SHIFT + P` to open the command palette). + "New File" animation +2. Name and save your file somewhere, and we’re good to go! +3. Start with some examples: you can find examples files and tutorials inside the comments, as well as in the notification pop up when you run the `"Device Simulator Express: [Circuit Playground Express] New File"` Command. -#### 2. Start from an existing python file. +#### III. Start from an existing Python file. 1. Open the folder or your .py file in Visual Studio Code. 2. Run `Device Simulator Express: [Circuit Playground Express] Open Simulator` from the command palette or icon in the editor toolbar. -#### 3. Run your code on the simulator. +#### IV. Run your code on the simulator. -How to run the simulator animation +How to run the simulator animation -- Run `Run Simulator` from the command palette or icon in the editor toolbar. -- You can use the `Play` or `Refresh` button on the simulator webview. +1. Run `Run Simulator` from the command palette or use the `Play` button on the simulator webview. -#### 4. Deploy your code to the physical device +#### V. Deploy your code to the physical device -Before deploying the python code to your CPX device, you need to format your device following these tutorials: +Before deploying the Python code to your CPX device, you need to format your device by following these tutorials: -1. Download the firmware with the .uf2 file (link: https://learn.adafruit.com/adafruit-circuit-playground-express/circuitpython-quickstart) +1. Download the firmware with the .uf2 file (link: https://learn.adafruit.com/adafruit-circuit-playground-express/circuitpython-quickstart). 2. Download the lastest version of the cpx library (link: https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries). -Then, if you are on Windows, you will also need to install the Python Pywin32 package. Use the following command in the console: `pip install pywin32` - -Deploy to Device +Deploy to Device -#### 5. Use the Serial Monitor for your Adafruit CPX device (available on Windows and Mac only) +#### VI. Use the Serial Monitor for your Adafruit CPX device (available on Windows and Mac only) -1. Plug in your CPX device (make sure it’s formatted properly already) -2. Run the command `"Device Simulator Express: Open Serial Monitor"` -3. Select your baud rate for the serial port -4. The print() statements in your code will show in the output console +1. Plug in your CPX device (make sure it’s formatted properly already). +2. Run the command `"Device Simulator Express: Open Serial Monitor"`. +3. Select your baud rate for the serial port. +4. The `print()` statements in your code will show in the output console. -#### 6. Use the sensors in the Device Simulator Express +#### VII. Use the sensors in the Device Simulator Express Generating input for the sensors can be done by interacting directly with device on the webview or by using the toolbar. - **Switch, push buttons and capacitive touch:** click directly on the corresponding element on the device or use the keybindings. -- **Temperature sensor, Light sensor, acceleration:** click on the corresponding button in the toolbar and change the value using the slider or the input box attached to it. +- **Temperature sensor, Light sensor, Acceleration sensor:** click on the corresponding button in the toolbar and change the value using the slider or the input box attached to it. - **Shake detection:** go to the motion sensor section in the toolbar and click on the shake button. -#### 7. Debug your project on the simulator +#### VIII. Debug your project on the simulator 1. Add breakpoints in your code 2. Press F5 to enter the debugging mode, and you can start debugging line by line! ### Commands -Device Simulator Express provides several commands in the Command Palette (F1 or Ctrl + Shift + P/ Cmd + Shift + P for Mac OS) for working with \*.py files: +Device Simulator Express provides several commands in the Command Palette (`F1` or `CTRL + SHIFT + P` / `CMD + SHIFT + P` for Mac OS) for working with \*.py files: +- `Device Simulator Express: Getting Started`: Opens a page in VS Code that helps users get started with the extension. Here, users can browse through code that they can use to play with the simulators. +- `Device Simulator Express: Run Simulator`: Runs Python code on the simulator. - `Device Simulator Express: [Circuit Playground Express] New File`: Opens an unsaved .py file with template code, also opens the simulator. - `Device Simulator Express: [Circuit Playground Express] Open Simulator`: Opens the simulator in the webView -- `Device Simulator Express: [Circuit Playground Express] Run on Simulator`: Runs python code on the simulator -- `Device Simulator Express: [Circuit Playground Express] Deploy to Device`: Copies & Pastes the current file to CIRCUITPY drive if detected a CPX is plugged in +- `Device Simulator Express: [Circuit Playground Express] Deploy to Device`: Copies the current file to CIRCUITPY drive if detected a CPX is plugged in. - `Device Simulator Express: Open Serial Monitor`: Opens the serial monitor in the integrated output window. - `Device Simulator Express: Close Serial Monitor`: Stops the serial monitor and releases the serial port. -- `Device Simulator Express: Change Baud Rate`: Changes the baud rate of the selected serial port. For Adafruit CPX and the BBC micro:bit, the default baud rate is 115200. +- `Device Simulator Express: Change Baud Rate`: Changes the baud rate of the selected serial port. For Adafruit CPX, the default baud rate is 115200. - `Device Simulator Express: Select Serial Port`: Changes the current serial port. ### Keybindings @@ -145,10 +155,10 @@ Device Simulator Express provides several commands in the Command Palette (F1 or In Device Simulator Express, you can use keyboard to interact with the device: - Push Button `A for A, B for B, C for A & B` -- Capacitive Touch Sensor `A1 – A7: SHIFT + 1~7` +- Capacitive Touch Sensor `A1 – A7: SHIFT + 1 ~ 7` - Slider Switch: `SHIFT + S` - Refresh the simulator: `SHIFT + R` - +- Run the simulator: `SHIFT + F` ## BBC micro:bit Simulator @@ -165,23 +175,87 @@ In Device Simulator Express, you can use keyboard to interact with the device: - Acceleration detection - Temperature sensor +### Useful Links +- Tutorials and Example Code for BBC micro:bit: + - [MicroPython documentation](https://microbit-micropython.readthedocs.io/en/latest/) + - [BBC micro:bit examples on the official micro:bit website](https://microbit.org/projects/make-it-code-it/?filters=python) + ### How to use + +#### I. Take a look at the "Device Simulator Express: Getting Started" Command. +1. Type in `"Device Simulator Express: [Circuit Playground Express] New File"` in the command palette (`CTRL + SHIFT + P` / `CMD + SHIFT + P` to open the command palette). +Deploy to Device +2. Choose the `micro:bit` option from the dropdown. +2. Read, copy and learn some of the things you can do with the simulator! + +#### II. Start with the "Device Simulator Express [micro:bit]: New File" Command. + +1. Type in `"Device Simulator Express: [micro:bit] New File"` in the command palette (`CTRL + SHFT + P / CMD + SHIFT + P` to open the command palette). + "New File" animation +2. Name and save your file somewhere, and we’re good to go! + +#### III. Start from an existing Python file. + +1. Open the folder or your .py file in Visual Studio Code. +2. Run `Device Simulator Express: [micro:bit] Open Simulator` from the command palette or icon in the editor toolbar. + +#### IV. Run your code on the simulator. + +How to run the simulator animation + +1. Run `Run Simulator` from the command palette or use the `Play` button on the simulator webview. + +#### V. Deploy your code to the physical device + +1. Run `[micro:bit] Deploy to Device` from the command palette + +Deploy to Device + +#### VI. Use the Serial Monitor for your BBC micro:bit device (available on Windows and Mac only) + +1. Plug in your BBC micro:bit. +2. Run the command `"Device Simulator Express: Open Serial Monitor"`. +3. Select your baud rate for the serial port. +4. The `print()` statements in your code will show in the output console. + +#### VII. Use the sensors in the Device Simulator Express + +Generating input for the sensors can be done by interacting directly with device on the webview +or by using the toolbar. + +- **Push buttons:** click directly on the buttons on the device or use the keybindings. +- **Temperature sensor, Light sensor, Acceleration sensor:** click on the corresponding button in the toolbar and change the value using the slider or the input box attached to it. + +#### VIII. Debug your project on the simulator + +1. Add breakpoints in your code +2. Press F5 to enter the debugging mode, and you can start debugging line by line! + +### Commands Using the simulator for the micro:bit is similar to using the one for the CPX. The only difference is that the commands in the command palette display `Device Simulator Express: [micro:bit] ` instead of `Device Simulator Express: [Circuit Playground Express] `. Currently, we support the following commands for micro:bit: +- `Device Simulator Express: Getting Started`: Opens a page in VS Code that helps users get started with the extension. Here, users can browse through code that they can use to play with the simulators. +- `Device Simulator Express: Run Simulator`: Runs Python code on the simulator. - `Device Simulator Express: [micro:bit] Open Simulator`: Opens an unsaved .py file with template code, also opens the simulator. -- `Device Simulator Express: [micro:bit] New File`: Opens the simulator in the webView - -Please review the CPX's ["How to use" guide](#How-to-use) for more info. +- `Device Simulator Express: [micro:bit] New File`: Opens the simulator in the webView. +- `Device Simulator Express: [micro:bit] Deploy to Device`: Copies the current file to the micro:bit if the device is detected. +- `Device Simulator Express: Open Serial Monitor`: Opens the serial monitor in the integrated output window. +- `Device Simulator Express: Close Serial Monitor`: Stops the serial monitor and releases the serial port. +- `Device Simulator Express: Change Baud Rate`: Changes the baud rate of the selected serial port. For BBC micro:bit, the default baud rate is 115200. +- `Device Simulator Express: Select Serial Port`: Changes the current serial port. ### Keybindings - Push Button `A for A, B for B, C for A & B` - Refresh the simulator: `SHIFT + R` +- Run the simulator: `SHIFT + F` ## Contribute -[See here for steps to run the extension locally.](/docs/developers-setup.md) +[See here for steps to run the extension locally.](https://github.com/microsoft/vscode-python-devicesimulator/blob/dev/docs/developers-setup.md) ## Provide feedback -To report issues, provide feedback or requests, please use this link: [Provide Feedback](https://aka.ms/AA5xpxx). +To add a review for our extension, please do so on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-python.devicesimulatorexpress) + +To report issues, provide feedback or requests, please use this link: [Provide Feedback](https://github.com/microsoft/vscode-python-devicesimulator/issues). We would love to hear from you about your experience to keep improving our project. ## Privacy and Telemetry Notice @@ -216,7 +290,7 @@ A `ThirdPartyNotices.txt` file is provided in the extension's source code listin - The first time you install the extension, you'll need to execute the `run` command at least once in order to access auto-completion. - While running a code file, if you get an error saying it can't find the file, make sure you've clicked on a valid Python code file before running it. - To open the output panel again after closing it go to VS Code menu: `View->Output`. -- If you try to deploy to the device while it's plugged in but you still get an error saying it cannot find the board, make sure your Circuit Playground Express is formatted correctly and that its name matches `CIRCUITPY`. +- If you try to deploy to the CPX while it's plugged in but you still get an error saying it cannot find the board, make sure your device is formatted correctly and that its name matches `CIRCUITPY`. - If you can't get the Simulator communication working while debugging, try to open your `Settings` and check the port used under `"Device Simulator Express: [] Debugger Server Port"`. You can either change it (usually ports above 5000 should work) or try to free it, then start debugging again. - When you are using the serial monitor, if you get some unusual error messages, unplug the device and reload the VS Code windows. diff --git a/assets/readmeFiles/cpx/cpx-deploy.png b/assets/readmeFiles/cpx/cpx-deploy.png new file mode 100644 index 000000000..efd87907d Binary files /dev/null and b/assets/readmeFiles/cpx/cpx-deploy.png differ diff --git a/assets/readmeFiles/cpx/cpx-img.png b/assets/readmeFiles/cpx/cpx-img.png new file mode 100644 index 000000000..67bdbd9a1 Binary files /dev/null and b/assets/readmeFiles/cpx/cpx-img.png differ diff --git a/assets/readmeFiles/cpx/cpx-new-file.gif b/assets/readmeFiles/cpx/cpx-new-file.gif new file mode 100644 index 000000000..41e0a7689 Binary files /dev/null and b/assets/readmeFiles/cpx/cpx-new-file.gif differ diff --git a/assets/readmeFiles/cpx/cpx-run.gif b/assets/readmeFiles/cpx/cpx-run.gif new file mode 100644 index 000000000..374389ccb Binary files /dev/null and b/assets/readmeFiles/cpx/cpx-run.gif differ diff --git a/assets/readmeFiles/getting_started.png b/assets/readmeFiles/getting_started.png new file mode 100644 index 000000000..ef6110bfa Binary files /dev/null and b/assets/readmeFiles/getting_started.png differ diff --git a/assets/readmeFiles/microbit/microbit-deploy.png b/assets/readmeFiles/microbit/microbit-deploy.png new file mode 100644 index 000000000..435d779ab Binary files /dev/null and b/assets/readmeFiles/microbit/microbit-deploy.png differ diff --git a/assets/readmeFiles/microbit/microbit-new-file.gif b/assets/readmeFiles/microbit/microbit-new-file.gif new file mode 100644 index 000000000..bb132ba05 Binary files /dev/null and b/assets/readmeFiles/microbit/microbit-new-file.gif differ diff --git a/assets/readmeFiles/microbit/microbit-run.gif b/assets/readmeFiles/microbit/microbit-run.gif new file mode 100644 index 000000000..658a14948 Binary files /dev/null and b/assets/readmeFiles/microbit/microbit-run.gif differ diff --git a/assets/readmeFiles/microbit/microbit.png b/assets/readmeFiles/microbit/microbit.png new file mode 100644 index 000000000..3d26d1002 Binary files /dev/null and b/assets/readmeFiles/microbit/microbit.png differ