diff --git a/README.md b/README.md index a1bd260be..fd3b3de8a 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,205 @@ # Project Pacifica -This project is a VS Code extension for makers to write for their microcontrollers and provide them a simulator to test their code. -This extension currently supports some features of the Adafruit Circuit Playground Express. +Make without limit! Pacifica, a Microsoft Garage project, allows you to code in CircuitPython for your awesome +Circuit Playground Express (CPX) projects! 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. -## Build Status +![](assets/readmeFiles/cpx.jpg?raw=true) -| Branch | Build Status | -| :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| dev | [![Build status](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_apis/build/status/Adafruit/Intern%20GitHub-CI?branchName=dev)](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_build/latest?definitionId=304&branchName=dev) | -| staging | [![Build Status](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_apis/build/status/Adafruit/Intern%20GitHub-CI?branchName=staging)](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_build/latest?definitionId=304&branchName=staging) | -| master | [![Build Status](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_apis/build/status/Adafruit/Intern%20GitHub-CI?branchName=master)](https://microsoftgarage.visualstudio.com/Intern%20GitHub/_build/latest?definitionId=304&branchName=master) | +## Features -## Code of conduct +- IntelliSense and syntax highlighting for CircuitPython code (only supports CPX Express library) +- Template file generation +- Integrated Python Debugging for the Simulator +- 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: + - Green LED + - Red LED + - Push Buttons A and B + - Slider Switch + - Speaker: Play .wav file + - 10 NeoPixels + - Light sensor + - Motion sensors + - Acceleration detection + - Device shake detection + - Temperature sensor + - 7 Capacitive Touch sensors -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. +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 Pacifica. +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! -## Documentation +## Prerequisites -- [Installation instructions](/docs/install.md) -- [How to use the Extension](/docs/how-to-use.md) -- [Setup for developers](/docs/developers-setup.md) -- [Contributing](CONTRIBUTING.md) +The following dependencies are required to install before launching Pacifica. +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.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 Pacifica. + +The following dependecies can be installed for you by the extension by clicking yes when you are prompted to. (2) + +- _**Playsound**_ + install by typing the following commands in a console: `pip install playsound` + +- _**Pywin 32**_ + install by typing the following commands in a console: `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) +- 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) + +## How to use + +To use Pacifica, install the extension from the marketplace and reload VS Code. + +### 1. Start with the “New File” Command. + +1. Type in “Pacifica: New File” in the command palette(`CTRL+SHIFT+P`to open the command palette). + ![](assets/readmeFiles/newFile.gif?raw=true) +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 `“Pacifica: New File”` Command. + +![](assets/readmeFiles/findExamples.jpg?raw=true) + +### 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 . + +![](assets/readmeFiles/run.gif?raw=true) + +- 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. + +### 4. 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: + +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. + +![](assets/readmeFiles/deployToBoard.png?raw=true) + +### 5. Use the Serial Monitor for your Adafruit CPX device(available 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 + +### 6. Use the sensors in the Pacifica Simulator + +Generating input for the sensors can be done by interacting directly with device on the webview +or by using the toolbar. + +![](assets/readmeFiles/slider_basedSensor.gif?raw=true) ![](assets/readmeFiles/otherSensors.gif?raw=true) + +- **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. +- **Shake detection:** go to the motion sensor section in the toolbar and click on the shake button. + +### 7. 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 + +Pacifica provides several commands in the Command Palette (F1 or Ctrl + Shift + P/ Cmd + Shift + P for Mac OS) for working with \*.py files: + +- `Pacifica: New File`: Opens an unsaved .py file with template code, also open the simulator. +- `Pacifica: Open Simulator`: Opens the simulator in the webView +- `Pacifica: Run on Simulator`: Runs python code on the simulator +- `Pacifica: Deploy to Board`: Copies & Pastes the code.py or main.py file to CIRCUITPY drive if detected a CPX is plugged in +- `Pacifica: Open Serial Monitor`: Opens the serial monitor in the integrated output window. +- `Pacifica: Close Serial Monitor`: Stops the serial monitor and releases the serial port. +- `Pacifica: Change Baud Rate`: Changes the baud rate of the selected serial port. For Adafruit CPX, the default baud rate is 115200. +- `Pacifica: Select Serial Port`: Changes the current serial port. + +## Keybindings + +In Pacifica, you can use keyboard to interact with the device: + +- Push Button `A & B: A B` +- Capacitive Touch Sensor `A1 – A7: SHIFT + 1~7` +- Slider Switch: `SHIFT + S` +- Refresh the simulator: `SHIFT + R` + +## Provide feedback + +To report issues, provide feedback or requests, please use this link: [Provide Feedback](https://aka.ms/AA5xpxx). +We would love to hear from you about your experience to keep improving our project. ## Privacy and Telemetry Notice -- [Data collection](PRIVACY.md) +Our extension is collecting anonymous data about your usage of our features to help us improve our product. You can find the Privacy Notice here: [Data collection](PRIVACY.md), as well as instructions on how to turn it off. ## Third Party Notice - [Third Party Notice](ThirdPartyNotices.txt) + +## Troubleshooting Tips + +- 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 `'Pacifica: 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 + + Project Pacifica + + Copyright (c) Microsoft Corporation. All rights reserved. + + MIT License + + 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. + +## 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. diff --git a/assets/readmeFiles/cpx.jpg b/assets/readmeFiles/cpx.jpg new file mode 100644 index 000000000..28765f4e5 Binary files /dev/null and b/assets/readmeFiles/cpx.jpg differ diff --git a/assets/readmeFiles/deployToBoard.png b/assets/readmeFiles/deployToBoard.png new file mode 100644 index 000000000..b4e18f8a4 Binary files /dev/null and b/assets/readmeFiles/deployToBoard.png differ diff --git a/assets/readmeFiles/findExamples.jpg b/assets/readmeFiles/findExamples.jpg new file mode 100644 index 000000000..ac1997ee7 Binary files /dev/null and b/assets/readmeFiles/findExamples.jpg differ diff --git a/assets/readmeFiles/newFile.gif b/assets/readmeFiles/newFile.gif new file mode 100644 index 000000000..76f7bbc99 Binary files /dev/null and b/assets/readmeFiles/newFile.gif differ diff --git a/assets/readmeFiles/otherSensors.gif b/assets/readmeFiles/otherSensors.gif new file mode 100644 index 000000000..76b2aa8f7 Binary files /dev/null and b/assets/readmeFiles/otherSensors.gif differ diff --git a/assets/readmeFiles/run.gif b/assets/readmeFiles/run.gif new file mode 100644 index 000000000..fb1fa4c96 Binary files /dev/null and b/assets/readmeFiles/run.gif differ diff --git a/assets/readmeFiles/slider_basedSensor.gif b/assets/readmeFiles/slider_basedSensor.gif new file mode 100644 index 000000000..5e1b8b3b0 Binary files /dev/null and b/assets/readmeFiles/slider_basedSensor.gif differ diff --git a/docs/developers-setup.md b/docs/developers-setup.md index 7235b2ce6..fca7481db 100644 --- a/docs/developers-setup.md +++ b/docs/developers-setup.md @@ -14,7 +14,7 @@ (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 +* Python Modules - **Note:** On extension activation you will be prompted asking if you want the modules to be automatically installed for you - Playsound @@ -31,9 +31,9 @@ - Application Insights - Run the command in a console : `pip install applicationinsights` -- VS Code +* VS Code -- Python extension for VS Code (download from VS Code market place) +* Python extension for VS Code (download from VS Code market place) ## Steps to Get Started Running the Extension in Debug Mode @@ -68,4 +68,4 @@ - `components/` - `cpx/` and `Simulator.tsx` : contain the React components and objects to display and handle the simulator webview - `toolbar/` : contains the React components used in the toolbar and the modal. - - `translation/en.json`: contains the constants that should be localized. To internationalize the extension you can add additional files with constants sharing the same id found in _en.json_, but with the translated value. + - `translation/en.json`: contains the constants that should be localized. To internationalize the extension you can add additional files with constants sharing the same id found in _en.json_, but with the translated values. diff --git a/docs/how-to-use.md b/docs/how-to-use.md index a4f3c68ba..67735ba0a 100644 --- a/docs/how-to-use.md +++ b/docs/how-to-use.md @@ -18,15 +18,15 @@ Commands are accessible through : - **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))_. -- **Select Serial Port** : selects the serial port of the board you want the serial monitor to interact with. (2) +* **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.)_ -- **Open Serial Monitor** : opens the serial monitor. (2) +* **Open Serial Monitor** : opens the serial monitor. (2) _(**Note :** A serial port must have been selected already)_. -- **Change Baud Rate** : changes the baud rate of the serial monitor. (2) +* **Change Baud Rate** : changes the baud rate of the serial monitor. (2) -- **Close Serial Montitor** : closes the serial monitor. (2) +* **Close Serial Montitor** : closes the serial monitor. (2) ## Available features @@ -35,7 +35,7 @@ Commands are accessible through : - Output panel for the simulator - Deploy to the physical device (if correctly formatted) - Debugger for the simulator -- Serial Monitor +- Serial Monitor (available on Windows and Mac only) - Device's features : - NeoPixels - Buttons (A & B) @@ -55,11 +55,11 @@ Commands are accessible through : - Auto-detect/format the device - Device's features - Sound sensor - - Tones - - Sound detection (3) - - IR transmitter (3) - - Motion sensors - - Tap detection + - Tones +- Sound detection (3) +- IR transmitter (3) +- Motion sensors + - Tap detection ## Pacifica configuration @@ -67,7 +67,7 @@ Here are the settings you can change in the Pacifica configuration: - **Debugger Server Port:** allows you to change the port used to communicate with the debugger. Default value is _5577_. (4) -- **Enable USBDetection:** when disabled, prevents the serial monitor from listening to messages from the serial port. +- **Enable USB Detection:** when disabled, prevents the serial monitor from listening to messages from the serial port. - **Show Device Icon In Editor Title Menu:** allows you to choose whether the _`Deploy to Device`_ button should be in the editor title. diff --git a/docs/install.md b/docs/install.md index 0d2f21bb7..39513f59a 100644 --- a/docs/install.md +++ b/docs/install.md @@ -17,17 +17,16 @@ _Note: You need to install all the dependencies in order to use the extension._ - [VS Code](https://code.visualstudio.com/Download) - [Node](https://nodejs.org/en/download/) -- [Python 3.7.4 (or latest)](https://www.python.org/downloads/) +- [Python 3.7.4](https://www.python.org/downloads/) - **Warning :** Make sure you've included `python` and `pip` to your `PATH` in your **environment variables**. _(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` in a terminal, the command is recognized.)_ -- Python VS Code extension (downloaded from VS Code Marketplace) +- [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 asking if you want the modules to be automatically installed for you + - **Note:** On extension activation you will be prompted asking if you want the modules to be automatically installed for you. - Playsound : `pip install playsound` - - Pywin32 : + - Pywin32 : `pip install pywin32` - **Note:** This is only needed for Windows computers - - `pip install pywin32` - Python-Socketio : `pip install python-socketio` - Requests : `pip install requests` - Application Insights: `pip install applicationinsights` diff --git a/locales/en/out/constants.i18n.json b/locales/en/out/constants.i18n.json index 010f27146..1bbea8a20 100644 --- a/locales/en/out/constants.i18n.json +++ b/locales/en/out/constants.i18n.json @@ -35,8 +35,8 @@ "info.privacyStatement": "Privacy Statement", "info.successfulInstall": "Successfully installed Python dependencies.", "info.thirdPartyWebsite": "By clicking \"Agree and Proceed\" you will be redirected to adafruit.com, a third party website not managed by Microsoft. Please note that your activity on adafruit.com is subject to Adafruit's privacy policy", - "info.welcomeOutputTab": "Welcome to the Adafruit Simulator output tab !\n\n", - "label.webviewPanel": "Adafruit CPX", + "info.welcomeOutputTab": "Welcome to the Pacifica Simulator output tab !\n\n", + "label.webviewPanel": "Pacifica Simulator", "name": "Pacifica Simulator", "warning.agreeAndRun": "By selecting ‘Agree and Run’, you understand the extension executes Python code on your local computer, which may be a potential security risk." -} \ No newline at end of file +} diff --git a/src/adafruit_circuitplayground/express.py b/src/adafruit_circuitplayground/express.py index 6077a68bf..85e38040a 100644 --- a/src/adafruit_circuitplayground/express.py +++ b/src/adafruit_circuitplayground/express.py @@ -154,7 +154,7 @@ def touch_A7(self): def adjust_touch_threshold(self, adjustement): """Not implemented! - The CPX Simulator doesn't use capacitive touch threshold. + The Pacifica Simulator doesn't use capacitive touch threshold. """ if(utils.telemetry_available() and not self.telemetry_state["ADJUST_THRESHOLD"]): utils.send_telemetry("ADJUST_THRESHOLD") diff --git a/src/constants.ts b/src/constants.ts index 5a13d85c6..95105263e 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -19,7 +19,7 @@ const localize: nls.LocalizeFunc = nls.config({ export const CONFIG = { SHOW_DEPENDENCY_INSTALL: "pacifica.showDependencyInstall", SHOW_NEW_FILE_POPUP: "pacifica.showNewFilePopup" -} +}; export const CONSTANTS = { DEBUG_CONFIGURATION_TYPE: "pacifica", @@ -178,7 +178,10 @@ export const CONSTANTS = { ), REDIRECT: localize("info.redirect", "You are being redirected."), RUNNING_CODE: localize("info.runningCode", "Running user code"), - SUCCESSFUL_INSTALL: localize("info.successfulInstall", "Successfully installed Python dependencies."), + SUCCESSFUL_INSTALL: localize( + "info.successfulInstall", + "Successfully installed Python dependencies." + ), THIRD_PARTY_WEBSITE: localize( "info.thirdPartyWebsite", 'By clicking "Agree and Proceed" you will be redirected to adafruit.com, a third party website not managed by Microsoft. Please note that your activity on adafruit.com is subject to Adafruit\'s privacy policy' diff --git a/src/device.py b/src/device.py index 767ac96bb..5eca629ee 100644 --- a/src/device.py +++ b/src/device.py @@ -12,7 +12,7 @@ import win32api -class Adafruit: +class Device: def __init__(self): self.connected = False self.error_message = None @@ -58,7 +58,7 @@ def find_device_directory(self): if __name__ == "__main__": import shutil - cpx = Adafruit() + cpx = Device() device_directory = cpx.find_device_directory() if cpx.error_message: print("{}:\t{}".format( diff --git a/src/view/translations/en.json b/src/view/translations/en.json index 2c98af38d..3f650da9b 100644 --- a/src/view/translations/en.json +++ b/src/view/translations/en.json @@ -1,8 +1,8 @@ { - "toolbar-gpio.description": "8 GPIOs on CPX! Pin A1 - A7 can also be used as capacitive touch sensors, and A0 is a true analog output pin.", + "toolbar-gpio.description": "8 GPIOs on the device! Pin A1 - A7 can also be used as capacitive touch sensors, and A0 is a true analog output pin.", "toolbar-gpio.title": "GPIO", "toolbar-gpio.tryItDescription": "Use your mouse to interact with the pin A1 - A7 or use your keyboard SHIFT+”1” - “7”", - "toolbar-ir-sensor.description": "Allows you to send commands to the CPX with a remote control, or even send messages between multiple CPXs! You can also do very simple proximity sensing since it reads the reflected light.", + "toolbar-ir-sensor.description": "Allows you to send commands to the device with a remote control, or even send messages between multiple devices! You can also do very simple proximity sensing since it reads the reflected light.", "toolbar-ir-sensor.title": "IR Transmit & Receiver", "toolbar-ir-sensor.tryItDescription": "We’re working hard to support this sensor on the simulator in the Pacifica. You can try it on MakeCode!", "toolbar-ir-sensor.tryItTitle": "We’re working hard to support this sensor on the simulator in the Pacifica. You can try it on MakeCode!", @@ -29,7 +29,7 @@ "toolbar-slider-switch.tryItDescription": "Click it with your mouse or press 'S' on your keyboard to switch it ON and OFF!", "toolbar-speaker.description": "This speaker can play .wav file and different tones and also has a class D amplifier that is connected to an output A0 pin built in! You can turn it off using the shutdown control on pin #11 on the physical device.", "toolbar-speaker.title": "Speaker", - "toolbar-speaker.tryItDescription": "Right now the tones are not supported yet on the simulator, but you can play it on your CPX!", + "toolbar-speaker.tryItDescription": "Right now the tones are not supported yet on the simulator, but you can play it on your device!", "toolbar-temperature-sensor.description": "This sensor uses an NTC thermistor to sense temperature an calculate it with the analog voltage on analog pin #A9.", "toolbar-temperature-sensor.title": "Temperature Sensor", "toolbar-temperature-sensor.tryItDescription": "You can set the temperature range from your code!"