Skip to content

Commit 7f2b941

Browse files
will-v-piwill-v-pi
committed
Add installation troubleshooting steps
1 parent 6f7707e commit 7f2b941

File tree

2 files changed

+168
-155
lines changed

2 files changed

+168
-155
lines changed

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 36 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,36 @@
1-
---
2-
name: Bug report
3-
about: Create a report to help us improve
4-
title: ''
5-
labels: ''
6-
assignees: ''
7-
8-
---
9-
10-
_Before filing a bug report, please try to reproduce your issue using the latest debug .vsix file from [GitHub Actions](https://github.com/raspberrypi/pico-vscode/actions/workflows/release.yml?query=branch%3Amain). This will provide more debug information than the release build._
11-
12-
**Describe the bug**
13-
A clear and concise description of what the bug is.
14-
15-
**Extension Logs**
16-
Relevant extracts of the extension log showing the errors with this extension, which can be viewed using Help -> Toggle Developer Tools and clicking on the Console.
17-
18-
**To Reproduce**
19-
Steps to reproduce the behavior:
20-
1. Go to '...'
21-
2. Click on '....'
22-
3. Scroll down to '....'
23-
4. See error
24-
25-
**Expected behavior**
26-
A clear and concise description of what you expected to happen.
27-
28-
**Screenshots**
29-
If applicable, add screenshots to help explain your problem.
30-
31-
**Platform (please complete the following information):**
32-
- OS: [e.g. Windows 11, macOS, Raspberry Pi OS]
33-
- Architecture: [e.g. x86, Arm64]
34-
35-
**Additional context**
36-
Add any other context about the problem here.
1+
---
2+
name: Bug report
3+
about: Create a report to help us improve
4+
title: ''
5+
labels: ''
6+
assignees: ''
7+
8+
---
9+
10+
_Before filing a bug report, please try to reproduce your issue using the latest debug .vsix file from [GitHub Actions](https://github.com/raspberrypi/pico-vscode/actions/workflows/release.yml?query=branch%3Amain). This will provide more debug information than the release build. You should also try the troubleshooting steps in the [README](https://github.com/raspberrypi/pico-vscode?tab=readme-ov-file#troubleshooting) to fix your issue._
11+
12+
**Describe the bug**
13+
A clear and concise description of what the bug is.
14+
15+
**Extension Logs**
16+
Relevant extracts of the extension log showing the errors with this extension, which can be viewed using Help -> Toggle Developer Tools and clicking on the Console.
17+
18+
**To Reproduce**
19+
Steps to reproduce the behavior:
20+
1. Go to '...'
21+
2. Click on '....'
22+
3. Scroll down to '....'
23+
4. See error
24+
25+
**Expected behavior**
26+
A clear and concise description of what you expected to happen.
27+
28+
**Screenshots**
29+
If applicable, add screenshots to help explain your problem.
30+
31+
**Platform (please complete the following information):**
32+
- OS: [e.g. Windows 11, macOS, Raspberry Pi OS]
33+
- Architecture: [e.g. x86, Arm64]
34+
35+
**Additional context**
36+
Add any other context about the problem here.

‎README.md‎

Lines changed: 132 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,119 +1,132 @@
1-
# Raspberry Pi Pico Visual Studio Code extension
2-
3-
> **Note: The extension is currently under development.**
4-
5-
This is the official Visual Studio Code extension for Raspberry Pi Pico development. This extension equips you with a suite of tools designed to streamline your Pico projects using Visual Studio Code and the official [Pico SDK](https://github.com/raspberrypi/pico-sdk).
6-
7-
For comprehensive setup instructions, refer to the [Getting Started guide](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf) PDF.
8-
9-
[Download latest Beta 📀](https://github.com/raspberrypi/pico-vscode/releases)
10-
11-
## Features
12-
13-
### Project Setup and Management
14-
15-
- **Project Generator**: Easily create and configure new projects with support for advanced Pico features like I2C and PIO. The generator targets the Ninja build system and allows customization during project creation.
16-
- **Quick Project Setup**: Initiate new Pico projects directly from the Explorer view, when no workspace is open.
17-
- **MicroPython Support**: Create and develop MicroPython-based Pico projects with support provided through the [MicroPico](https://github.com/paulober/MicroPico) extension.
18-
19-
### Configuration and Tool Management
20-
21-
- **Automatic CMake Configuration**: Automatically configures CMake when loading a project.
22-
- **Version Switching**: Seamlessly switch between different versions of the Pico SDK and tools.
23-
- **No Manual Setup Required**: Automatically handles environment variables, toolchain, SDK, and tool management.
24-
- **Includes an Uninstaller**: Easily remove the extension along with all automatically installed tools and SDKs.
25-
26-
### Build, Debug, and Documentation
27-
28-
- **One-Click Compilation and Debugging**: Automatically configure OpenOCD, Ninja, and CMake, allowing you to compile and debug with a single click.
29-
- **Offline Documentation**: Conveniently access Pico SDK documentation directly within the editor, even when offline.
30-
31-
- **Version Switching**: Seamlessly switch between different versions of the Pico SDK and tools.
32-
- **No Manual Setup Required**: The extension handles environment variables, toolchain, SDK, and tool management for you.
33-
- **One-Click Compilation**: Compile projects directly from the status bar with your selected SDK and tools.
34-
- **Offline Documentation**: Access Pico SDK documentation offline.
35-
- **Quick Project Setup**: Quickly create new Pico projects from the Explorer view when no workspace is open.
36-
- **MicroPython Support**: Create MicroPython-based Pico projects with support provided through the MicroPico extension.
37-
38-
## Requirements by OS
39-
40-
> **Supported Platforms: Raspberry Pi OS (64-bit), Windows 10/11 (x86_64), macOS Sonoma (14.0) and newer, Linux x64 and arm64**
41-
42-
- Visual Studio Code v1.92.1 or later
43-
44-
### Raspberry Pi OS and Windows
45-
46-
No additional requirements are needed.
47-
48-
### macOS
49-
To meet the requirements for macOS, run the following command in Terminal to install necessary tools:
50-
```zsh
51-
xcode-select --install
52-
```
53-
This command installs all of the necessary tools, including but not limited to:
54-
- **Git 2.28 or later** (ensure it's in your PATH)
55-
- **Tar** (ensure it's in your PATH)
56-
57-
### Linux
58-
- **Python 3.9 or later** (ensure it’s in your PATH or set in settings)
59-
- **Git 2.28 or later** (ensure it’s in your PATH)
60-
- **Tar** (ensure it’s in your PATH)
61-
- **\[Optional\]** gdb-multiarch for debugging (x86_64 only)
62-
- **\[Optional\]** udev rules installed to use [OpenOCD](https://github.com/raspberrypi/openocd/blob/sdk-2.0.0/contrib/60-openocd.rules) and [picotool](https://github.com/raspberrypi/picotool/blob/master/udev/99-picotool.rules) without `sudo`, for debugging and loading
63-
- For **\[Ubuntu 22.04\]**, install `libftdi1-2` and `libhidapi-hidraw0` packages to use OpenOCD
64-
65-
## Extension Settings
66-
67-
This extension provides the following settings:
68-
69-
* `raspberry-pi-pico.cmakePath`: Specify a custom path for CMake.
70-
* `raspberry-pi-pico.python3Path`: Specify a custom path for Python 3 _(machine scoped)_.
71-
* `raspberry-pi-pico.ninjaPath`: Specify a custom path for Ninja.
72-
* `raspberry-pi-pico.gitPath`: Specify a custom path for Git.
73-
* `raspberry-pi-pico.cmakeAutoConfigure`: Enable/Disable automatic CMake configuration when project is opened
74-
* `raspberry-pi-pico.useCmakeTools`: Enable/Disable the CMake Tools Extension Integration (see below)
75-
* `raspberry-pi-pico.githubToken`: Provide a GitHub personal access token (classic) with the `public_repo` scope. This token is used to check for available versions of the Pico SDK and other tools. Without it, the extension uses the unauthenticated GitHub API, which has a lower rate limit and may lead to restricted functionality if the limit is exceeded. The unauthenticated rate limit is per public IP address, so a token is more necessary if your IP is shared with many users.
76-
77-
## CMake Tools Extension Integration
78-
79-
For more complex projects, such as those with multiple executables or when the project name is defined as a variable, this extension can integrate with the CMake Tools extension to enhance CMake parsing. You can enable the CMake Tools Extension integration during project generation, using the checkbox at the bottom of the page. To enable it for an existing project, just re-import the project with the option selected. Alternatively, to manually enable it, adjust the following settings in your `settings.json`:
80-
81-
- `raspberry-pi-pico.cmakeAutoConfigure`: Set from `true` to `false`.
82-
- `raspberry-pi-pico.useCmakeTools`: Set from `false` to `true`.
83-
84-
For optimal functionality, consider enabling:
85-
86-
- `cmake.configureOnEdit`: true
87-
- `cmake.automaticReconfigure`: true
88-
- `cmake.configureOnOpen`: true
89-
90-
When prompted, select the `Pico` kit in CMake Tools, and set your build and launch targets accordingly. Use CMake Tools for compilation, but continue using this extension for debugging, as CMake Tools debugging is not compatible with Pico.
91-
92-
## VS Code Profiles
93-
94-
If you work with multiple microcontroller toolchains, consider installing this extension into a [VS Code Profile](https://code.visualstudio.com/docs/editor/profiles) to avoid conflicts with other toolchains. Follow these steps:
95-
96-
1. Download the sample profile from [here](scripts/Pico.code-profile).
97-
2. Open Command Palette with `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select `Profiles: Import Profile`.
98-
3. Import the downloaded file to install the extension in a dedicated Pico profile.
99-
4. This setup helps isolate the Pico extension from other extensions, reducing the risk of conflicts.
100-
101-
## Known Issues
102-
103-
- Custom Paths: Custom paths for Ninja, Python3, and Git are not stored in `CMakeLists.txt` like SDK and Toolchain paths. You need to build and configure projects through the extension to use these custom paths.
104-
105-
### GitHub API Rate Limit ("Error while retrieving SDK and toolchain versions")
106-
107-
If you encounter issues retrieving available Pico SDK versions, it may be due to GitHub API rate limits. To resolve this, create a personal access token (classic PAT) with the `public_repo` scope and set it in the global (User) extension settings to increase your rate limit.
108-
109-
## Build Instructions
110-
111-
For advanced users who want to build the extension `.vsix` file, follow these steps:
112-
113-
1. Install nodejs ([Instructions Windows](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows))
114-
2. Update npm: `npm install -g npm`
115-
3. Install VSCE globally: `npm install -g @vscode/vsce`
116-
4. Run `npm ci` in the project directory to install dependencies.
117-
5. Build the extension with: `vsce package`
118-
119-
This will generate a `.vsix` file, which you can install in VS Code using `code --install-extension path-to.vsix` or via the GUI: `Extensions > three dots > Install from VSIX`.
1+
# Raspberry Pi Pico Visual Studio Code extension
2+
3+
> **Note: The extension is currently under development.**
4+
5+
This is the official Visual Studio Code extension for Raspberry Pi Pico development. This extension equips you with a suite of tools designed to streamline your Pico projects using Visual Studio Code and the official [Pico SDK](https://github.com/raspberrypi/pico-sdk).
6+
7+
For comprehensive setup instructions, refer to the [Getting Started guide](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf) PDF.
8+
9+
If you have any issues while installing, please check out the [Troubleshooting](#troubleshooting) section.
10+
11+
[Download latest Beta 📀](https://github.com/raspberrypi/pico-vscode/releases)
12+
13+
## Features
14+
15+
### Project Setup and Management
16+
17+
- **Project Generator**: Easily create and configure new projects with support for advanced Pico features like I2C and PIO. The generator targets the Ninja build system and allows customization during project creation.
18+
- **Quick Project Setup**: Initiate new Pico projects directly from the Explorer view, when no workspace is open.
19+
- **MicroPython Support**: Create and develop MicroPython-based Pico projects with support provided through the [MicroPico](https://github.com/paulober/MicroPico) extension.
20+
21+
### Configuration and Tool Management
22+
23+
- **Automatic CMake Configuration**: Automatically configures CMake when loading a project.
24+
- **Version Switching**: Seamlessly switch between different versions of the Pico SDK and tools.
25+
- **No Manual Setup Required**: Automatically handles environment variables, toolchain, SDK, and tool management.
26+
- **Includes an Uninstaller**: Easily remove the extension along with all automatically installed tools and SDKs.
27+
28+
### Build, Debug, and Documentation
29+
30+
- **One-Click Compilation and Debugging**: Automatically configure OpenOCD, Ninja, and CMake, allowing you to compile and debug with a single click.
31+
- **Offline Documentation**: Conveniently access Pico SDK documentation directly within the editor, even when offline.
32+
33+
- **Version Switching**: Seamlessly switch between different versions of the Pico SDK and tools.
34+
- **No Manual Setup Required**: The extension handles environment variables, toolchain, SDK, and tool management for you.
35+
- **One-Click Compilation**: Compile projects directly from the status bar with your selected SDK and tools.
36+
- **Offline Documentation**: Access Pico SDK documentation offline.
37+
- **Quick Project Setup**: Quickly create new Pico projects from the Explorer view when no workspace is open.
38+
- **MicroPython Support**: Create MicroPython-based Pico projects with support provided through the MicroPico extension.
39+
40+
## Requirements by OS
41+
42+
> **Supported Platforms: Raspberry Pi OS (64-bit), Windows 10/11 (x86_64), macOS Sonoma (14.0) and newer, Linux x64 and arm64**
43+
44+
- Visual Studio Code v1.92.1 or later
45+
46+
### Raspberry Pi OS and Windows
47+
48+
No additional requirements are needed.
49+
50+
### macOS
51+
To meet the requirements for macOS, run the following command in Terminal to install necessary tools:
52+
```zsh
53+
xcode-select --install
54+
```
55+
This command installs all of the necessary tools, including but not limited to:
56+
- **Git 2.28 or later** (ensure it's in your PATH)
57+
- **Tar** (ensure it's in your PATH)
58+
59+
### Linux
60+
- **Python 3.9 or later** (ensure it’s in your PATH or set in settings)
61+
- **Git 2.28 or later** (ensure it’s in your PATH)
62+
- **Tar** (ensure it’s in your PATH)
63+
- **\[Optional\]** gdb-multiarch for debugging (x86_64 only)
64+
- **\[Optional\]** udev rules installed to use [OpenOCD](https://github.com/raspberrypi/openocd/blob/sdk-2.0.0/contrib/60-openocd.rules) and [picotool](https://github.com/raspberrypi/picotool/blob/master/udev/99-picotool.rules) without `sudo`, for debugging and loading
65+
- For **\[Ubuntu 22.04\]**, install `libftdi1-2` and `libhidapi-hidraw0` packages to use OpenOCD
66+
67+
## Extension Settings
68+
69+
This extension provides the following settings:
70+
71+
* `raspberry-pi-pico.cmakePath`: Specify a custom path for CMake.
72+
* `raspberry-pi-pico.python3Path`: Specify a custom path for Python 3 _(machine scoped)_.
73+
* `raspberry-pi-pico.ninjaPath`: Specify a custom path for Ninja.
74+
* `raspberry-pi-pico.gitPath`: Specify a custom path for Git.
75+
* `raspberry-pi-pico.cmakeAutoConfigure`: Enable/Disable automatic CMake configuration when project is opened
76+
* `raspberry-pi-pico.useCmakeTools`: Enable/Disable the CMake Tools Extension Integration (see below)
77+
* `raspberry-pi-pico.githubToken`: Provide a GitHub personal access token (classic) with the `public_repo` scope. This token is used to check for available versions of the Pico SDK and other tools. Without it, the extension uses the unauthenticated GitHub API, which has a lower rate limit and may lead to restricted functionality if the limit is exceeded. The unauthenticated rate limit is per public IP address, so a token is more necessary if your IP is shared with many users.
78+
79+
## CMake Tools Extension Integration
80+
81+
For more complex projects, such as those with multiple executables or when the project name is defined as a variable, this extension can integrate with the CMake Tools extension to enhance CMake parsing. You can enable the CMake Tools Extension integration during project generation, using the checkbox at the bottom of the page. To enable it for an existing project, just re-import the project with the option selected. Alternatively, to manually enable it, adjust the following settings in your `settings.json`:
82+
83+
- `raspberry-pi-pico.cmakeAutoConfigure`: Set from `true` to `false`.
84+
- `raspberry-pi-pico.useCmakeTools`: Set from `false` to `true`.
85+
86+
For optimal functionality, consider enabling:
87+
88+
- `cmake.configureOnEdit`: true
89+
- `cmake.automaticReconfigure`: true
90+
- `cmake.configureOnOpen`: true
91+
92+
When prompted, select the `Pico` kit in CMake Tools, and set your build and launch targets accordingly. Use CMake Tools for compilation, but continue using this extension for debugging, as CMake Tools debugging is not compatible with Pico.
93+
94+
## VS Code Profiles
95+
96+
If you work with multiple microcontroller toolchains, consider installing this extension into a [VS Code Profile](https://code.visualstudio.com/docs/editor/profiles) to avoid conflicts with other toolchains. Follow these steps:
97+
98+
1. Download the sample profile from [here](scripts/Pico.code-profile).
99+
2. Open Command Palette with `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select `Profiles: Import Profile`.
100+
3. Import the downloaded file to install the extension in a dedicated Pico profile.
101+
4. This setup helps isolate the Pico extension from other extensions, reducing the risk of conflicts.
102+
103+
## Troubleshooting
104+
105+
If you're having issues with installation, this is usually due to a download failure. To retry downloading everything, you can:
106+
- Clear all setting for the extension (`Ctrl+Shift+P` -> `Preferences: Open Settings (UI)` -> Search for `raspberry-pi-pico` and reset everything to default)
107+
- Uninstall the SDK (`Ctrl+Shift+P` -> `Raspberry Pi Pico: Uninstall Pico SDK`)
108+
- Uninstall the extension, close & reopen VS Code, then reinstall the extension
109+
110+
Also make sure you've deleted any previous SDK installations (eg Pico setup for Windows, or a manual installation you've done), as those can conflict with this extension.
111+
112+
If you're still unable to get it working, then [file a bug report](https://github.com/raspberrypi/pico-vscode/issues/new?template=bug_report.md) and **fill out all the fields** so we can figure out the problem.
113+
114+
## Known Issues
115+
116+
- Custom Paths: Custom paths for Ninja, Python3, and Git are not stored in `CMakeLists.txt` like SDK and Toolchain paths. You need to build and configure projects through the extension to use these custom paths.
117+
118+
### GitHub API Rate Limit ("Error while retrieving SDK and toolchain versions")
119+
120+
If you encounter issues retrieving available Pico SDK versions, it may be due to GitHub API rate limits. To resolve this, create a personal access token (classic PAT) with the `public_repo` scope and set it in the global (User) extension settings to increase your rate limit.
121+
122+
## Build Instructions
123+
124+
For advanced users who want to build the extension `.vsix` file, follow these steps:
125+
126+
1. Install nodejs ([Instructions Windows](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/nodejs-on-windows))
127+
2. Update npm: `npm install -g npm`
128+
3. Install VSCE globally: `npm install -g @vscode/vsce`
129+
4. Run `npm ci` in the project directory to install dependencies.
130+
5. Build the extension with: `vsce package`
131+
132+
This will generate a `.vsix` file, which you can install in VS Code using `code --install-extension path-to.vsix` or via the GUI: `Extensions > three dots > Install from VSIX`.

0 commit comments

Comments
 (0)