## Features
@@ -29,7 +29,7 @@ monitor allows you to observe the device output.
- Temperature sensor
- 7 Capacitive Touch sensors
-The simulator supports most of the sensors on CPX except **IR transmitter & Receiver**, **Sound Sensor (microphone)**, **Speaker (Play Tone)** and the **“tap” on Motion Sensor**.
+The simulator supports most of the sensors on CPX except **IR transmitter & Receiver**, **Sound Sensor (microphone)**, **Speaker (Play Tone)** and the **"tap" on Motion Sensor**.
The code related to these sensors can still run on the actual CPX board and be deployed using Device Simulator Express.
As we only support CPX library now, other libraries (i.e. simpleio) can’t run on the simulator. But they will work on the actual device!
@@ -43,53 +43,49 @@ You will be prompted to install the Python dependencies during the first use.
- _**[Python 3.7.4](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.
-The following dependecies can be installed for you by the extension by clicking yes when you are prompted to (**except** `pywin32` which is needed only on Windows platform). (2)
+- Python Modules for Simulation
+ - **Note:** On extension activation, you will be prompted with a popup message asking if you want the modules to be automatically installed for you. The following Python modules should be downloaded when you select "yes" on the prompt message. **If modules are not installed correctly, please use the "pip install" commands listed below.**
+ - Playsound : `pip install playsound`
+ - Pywin32 : `pip install pywin32`
+ - On Windows, you need to use the above command in the console to manually install pywin32.
+ - Python-Socketio : `pip install python-socketio`
+ - Requests : `pip install requests`
+ - Application Insights: `pip install applicationinsights`
-- _**Playsound**_
- install by typing the following commands in a console: `pip install playsound`
-
-- _**Pywin 32**_
- install by typing the following commands in a console (only for Windows computers, you must run it manually): `pip install pywin32`
-- _**Python-Socketio**_
- install by typing the following commands in a console: `pip install python-socketio`
-- _**Requests**_
- install by typing the following commands in a console: `pip install requests`
-- _**Application Insights**_
- install by typing the following commands in a console: `pip install applicationinsights`
## Useful Links
-
- Tutorials and Example Code for Adafruit CPX:
- - Adafruit CPX library tutorial: (https://learn.adafruit.com/circuitpython-made-easy-on-circuit-playground-express/circuit-playground-express-library)
- - Adafruit CPX Examples on GitHub: (https://github.com/adafruit/Adafruit_CircuitPython_CircuitPlayground/tree/master/examples)
- - Adafruit CPX Guided Tour (Intro for the Hardware) (https://learn.adafruit.com/adafruit-circuit-playground-express/guided-tour)
+ - [Adafruit CPX library tutorial](https://learn.adafruit.com/circuitpython-made-easy-on-circuit-playground-express/circuit-playground-express-library)
+ - [Adafruit CPX Examples on GitHub](https://github.com/adafruit/Adafruit_CircuitPython_CircuitPlayground/tree/master/examples)
+ - [Adafruit CPX Guided Tour (Intro for the Hardware)](https://learn.adafruit.com/adafruit-circuit-playground-express/guided-tour)
- Format Adafruit CPX device:
- - Tutorial for formatting Adafruit CPX for CircuitPython (https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
- - Download Firmware .uf2 file (https://learn.adafruit.com/adafruit-circuit-playground-express/circuitpython-quickstart)
- - Download the latest version of the Adafruit CPX library (link: https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries)
+ - [Tutorial for formatting Adafruit CPX for CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython)
+ - [Download Firmware .uf2 file](https://learn.adafruit.com/adafruit-circuit-playground-express/circuitpython-quickstart)
+ - [Download the latest version of the Adafruit CPX library](https://learn.adafruit.com/welcome-to-circuitpython/circuitpython-libraries)
+- For developers:
+ - [Steps to run the extension locally](/docs/developers-setup.md)
## How to use
To use Device Simulator Express, install the extension from the marketplace and reload VS Code.
-### 1. Start with the “New File” Command.
+### 1. Start with the "New File" Command.
-1. Type in Device Simulator Express: New File” in the command palette(`CTRL+SHIFT+P`to open the command palette).
- 
-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: New File”` Command.
+1. Type in `"Device Simulator Express: New File"` in the command palette (`CTRL+SHIFT+P` to open the command palette).
+
+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: New File"` Command.
-
+
### 2. Start from an existing python file.
1. Open the folder or your .py file in Visual Studio Code.
2. Run `open Simulator` from the command palette or icon in the editor toolbar.
-### 3. Run your code on the simulator .
+### 3. Run your code on the simulator.
-
+
- 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.
@@ -100,14 +96,16 @@ Before deploying the python code to your CPX device, you need to format your dev
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).
- **_Note:_** Make sure you name your file main.py or code.py: the device automatically runs the first file that is likely named.
+ **_Note:_** Make sure you name your file `main.py` or `code.py`: the device automatically runs the first file that is likely named. This is the convention for CircuitPython ([source](https://learn.adafruit.com/welcome-to-circuitpython/creating-and-editing-code#naming-your-program-file-7-32)).
+
+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`
-
+
-### 5. Use the Serial Monitor for your Adafruit CPX device(available Windows and Mac only)
+### 5. 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`
+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
@@ -129,10 +127,10 @@ or by using the toolbar.
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: New File`: Opens an unsaved .py file with template code, also open the simulator.
+- `Device Simulator Express: New File`: Opens an unsaved .py file with template code, also opens the simulator.
- `Device Simulator Express: Open Simulator`: Opens the simulator in the webView
- `Device Simulator Express: Run on Simulator`: Runs python code on the simulator
-- `Device Simulator Express: Deploy to Board`: Copies & Pastes the code.py or main.py file to CIRCUITPY drive if detected a CPX is plugged in
+- `Device Simulator Express: Deploy to Device`: Copies & Pastes the code.py or main.py 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, the default baud rate is 115200.
@@ -184,9 +182,8 @@ 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 have pylint enabled, it might underline the import of the adafruit_circuitplayground library, but it will work correctly.
- 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 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.
+- 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.
## License
@@ -217,6 +214,6 @@ A `ThirdPartyNotices.txt` file is provided in the extension's source code listin
## Notes
-(1) Note: the easiest way to do it is to select the "Add to PATH" option directly when you install Python. Otherwise you can search how to insert it manually, but make sure that when you type _python_ in a terminal, the command is recognized and have the correct version.
-(2) You can chose to see to see the prompt or not by changing the extension configirations.
-(3) To be able to run the file from your physical device, it should either be named code.py or main.py.
+1. Make sure that when you type _python_ in a terminal, the command is recognized and you have the correct version. The easiest way to do it is to select the "Add to PATH" option directly when you install Python. Otherwise you can search how to insert it manually.
+2. You can choose to see the prompt or not by changing the extension configurations.
+3. To be able to run the file on your physical device, it should either be named code.py or main.py.
diff --git a/ThirdPartyNotices.txt b/ThirdPartyNotices.txt
index e1c8043aa..26648250b 100644
--- a/ThirdPartyNotices.txt
+++ b/ThirdPartyNotices.txt
@@ -5771,6 +5771,64 @@ Copyright 2018 Kenneth Reitz
limitations under the License.
+Jest
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+Black
+The MIT License (MIT)
+
+Copyright (c) 2018 Łukasz Langa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+Prettier
+Copyright © James Long and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
-------------------------------------------------------------------
-------------------------------------------------------------------
diff --git a/docs/developers-setup.md b/docs/developers-setup.md
index d9eb3a2b1..a31842a89 100644
--- a/docs/developers-setup.md
+++ b/docs/developers-setup.md
@@ -13,29 +13,23 @@
- **NOTE :** Make sure pip is added to your environment variables as well
(for example it could be found at : `c:\users\<...>\appdata\local\programs\python\python37\lib\site-packages\pip`)
- Run in a console `python -m pip install --upgrade pip`
-
+
* Python Modules
-
- - **Note:** On extension activation you will be prompted a popup asking if you want the modules to be automatically installed for you, **except** `pywin32` which is needed only on Windows platform.
- - Playsound
- - Run the command in a console : `pip install playsound`
- - pytest
- - Run the command in a console : `pip install pytest`
- - Pywin32
- - **Note:** This is only needed for Windows computers. You must install it manually with the above command!
- - Run the command in a console : `pip install pywin32`
- - Python-Socketio
- - Run the command in a console : `pip install python-socketio`
- - Requests
- - Run the command in a console : `pip install requests`
- - Application Insights
- - Run the command in a console : `pip install applicationinsights`
-
+ - **Note:** On extension activation, you will be prompted with a popup asking if you want the modules to be automatically installed for you. The following python modules should be downloaded when you select "yes" on the prompt message.
+ - pywin32 **(on Windows only)**
+ - On Windows, you need to use the following command in the console to manually install pywin32: `pip install pywin32`
+ - *playsound*
+ - *pytest*
+ - *python-socketio*
+ - *requests*
+ - *applicationinsights*
+
+ *italics*: used in simulation mode only
* VS Code
* Python extension for VS Code (download from VS Code market place)
-## Steps to Get Started Running the Extension in Debug Mode
+## Steps to Get Started Running the Extension Locally
1. Make sure you have all the dependencies installed (Node, Python, Playsound, VS Code, Python VS Code extension)
@@ -47,17 +41,30 @@
5. Run the command : `npm run compile`
-6. Start debugging the extension by pressing F5 or going to VS Code Debug menu and select 'Start debugging'
+6. Start running the extension locally by pressing F5 or going to VS Code Debug menu and select 'Start debugging'
+
+## Testing
+
+- To run unit tests, run the command: `npm run test` in the root level directory.
+ - You will need Pytest installed for the Python tests to run correctly
+- To run just the python tests, run the command: `pytest src` or `python -m pytest src` in the root level directory.
## Notes on how to use it
- [Documentation to use the Extension](/docs/how-to-use.md)
-- Debugging the extension opens a new VS Code window with the extension installed
+- Debugging the extension opens a new VS Code window with the local build of the extension
- From the original VS Code window (opened in our repository) you can see outputs in the Debug Console
- In the new VS Code window, you can access the commands provided by the extension from the Commands Palette (Ctrl+Shift+P)
listed as 'Device Simulator Express : ...'
- If you change some files you'll need to run the 'npm run compile' command again and restart debugging
+## Formatting
+
+- We use prettier to format the Typescript and CSS files, and we use black to format the Python files.
+ - You will need to install them, if they are not installed already. This can be done by running the command: `npm install prettier` and `pip install black` respectively.
+- To check that your files are formatted correctly, run the command: `npm run check`.
+- To format your files correctly, run the command: `npm run format`.
+
## Repository Structure (important files)
- src
diff --git a/docs/how-to-use.md b/docs/how-to-use.md
index 6f6892ab4..09c497710 100644
--- a/docs/how-to-use.md
+++ b/docs/how-to-use.md
@@ -2,7 +2,7 @@
Commands are accessible through :
-- **The command palette** (`Ctrl+shift+P` or `View->Command Palette`) and type 'Device Simulator Express : `command_name`'
+- **The command palette** (`Ctrl+Shift+P` or `View->Command Palette`) and type 'Device Simulator Express : `command_name`'
- **The extension buttons** available on the top right of the Text Editor Panel when you have a Python file open (1)
## Available commands
@@ -12,11 +12,11 @@ Commands are accessible through :
- **New File** : opens an unsaved file with links to help you and a code snippet that you can save as `code.py` / `main.py`.
_(**Note :** will open the simulator webview if it's not open yet)_.
-- **Run Simulator** : run the code you have open on the simulator (make sure you've clicked on a valid code file).
+- **Run Simulator** : runs the code you have opened in the simulator (make sure you've clicked on a valid code file).
_(**Note :** will open the simulator webview if it's not open yet)_.
- **Deploy to Device** : saves the code to a Circuit Playground Express.
- _(**Note :** the board needs to be correctly formatted to a `CIRCUITPY` drive first if it's not the case : [Installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython))_.
+ _(**Note :** the board needs to be correctly formatted to a `CIRCUITPY` drive first. If that's not the case check [Installing CircuitPython](https://learn.adafruit.com/welcome-to-circuitpython/installing-circuitpython) to correctly format it)_.
* **Select Serial Port** : selects the serial port of the board you want the serial monitor to interact with. (2)
_(**Note :** USB detection must be enabled in the extension settings.)_
@@ -82,7 +82,6 @@ Here are the settings you can change in the Device Simulator Express configurati
- 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 have pylint enabled, it might underline the import of the adafruit_circuitplayground library, but it will work correctly.
- 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 can't get the Simulator communication working while debugging, try to open you `Settings` and check the port used under `'Device Simulator Express: Debugger Server Port'`. You can either change it (usually ports above 5000 could work) or try to free it, then start debugging again.
diff --git a/docs/install.md b/docs/install.md
index b0d782d2d..8a8421d6e 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -22,15 +22,18 @@ _Note: You need to install all the dependencies in order to use the extension._
_(Note: the easiest way to do it might be when you install Python, you can select the "Add to PATH" option directly. Otherwise you can search how to insert it manually, but make sure that when you type `python` (or `python3.7`) in a terminal, the command is recognized.)_
- [Python VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
- **Note:** This extension is installed automatically from the marketplace when you install our extension
-- Python Modules
- - **Note:** On extension activation you will be prompted a popup asking if you want the modules to be automatically installed for you, **except** `pywin32` which is needed only on Windows platform.
- - Playsound : `pip install playsound`
- - Pywin32 : `pip install pywin32`
- - **Note:** This is only needed for Windows computers. You must install it manually with the above command!
- - Python-Socketio : `pip install python-socketio`
- - Requests : `pip install requests`
- - Application Insights: `pip install applicationinsights`
+
+* Python Modules
+ - **Note:** On extension activation, you will be prompted with a popup asking if you want the modules to be automatically installed for you. The following python modules should be downloaded when you select "yes" on the prompt message. **If modules are not installed correctly, please use the "pip install" commands listed below.**
+ - pywin32 **(on Windows only)**: `pip install pywin32`
+ - On Windows, you need to use the above command in the console to manually install pywin32.
+ - *playsound*: `pip install playsound`
+ - *pytest*: `pip install pytest`
+ - *python-socketio*: `pip install python-socketio`
+ - *requests*: `pip install requests`
+ - *applicationinsights*: `pip install applicationinsights`
+ *italics*: used in simulation mode only
## How to use the Extension
- [How to use the Extension](/docs/how-to-use.md)
diff --git a/gulpfile.js b/gulpfile.js
index fdc6fcac2..3c106798d 100644
--- a/gulpfile.js
+++ b/gulpfile.js
@@ -25,7 +25,7 @@ const languages = [{ folderName: "en", id: "en" }];
gulp.task("clean", () => {
return del(
[
- "out/!(python_libs)",
+ "out/*",
"package.nls.*.json",
"../../dist/*0.0.0-UNTRACKEDVERSION.vsix"
],
@@ -36,7 +36,7 @@ gulp.task("clean", () => {
const pythonToMove = [
"./src/adafruit_circuitplayground/*.*",
"./src/*.py",
- "./src/requirements.txt"
+ "./src/requirements.txt",
];
gulp.task("python-compile", () => {
diff --git a/jest.config.js b/jest.config.js
new file mode 100644
index 000000000..3d7f4f549
--- /dev/null
+++ b/jest.config.js
@@ -0,0 +1,28 @@
+module.exports = {
+ // The root of your source code, typically /src
+ // `