diff --git a/howto/README.md b/howto/README.md
index c66f4e1..af38939 100644
--- a/howto/README.md
+++ b/howto/README.md
@@ -4,7 +4,7 @@ For applications that use pico-sdk (pico-examples, etc. ... this is true of near
 
 ## debugging Pico applications with pico-debug
 
-For OpenOCD users (including Visual Studio Code, etc.), after following the above steps on building Pico applications, please follow the instructions in [openocd.md](openocd.md).
+For OpenOCD users (including [Visual Studio Code](https://code.visualstudio.com/), etc.), after following the above steps on building Pico applications, please follow the instructions in [openocd.md](openocd.md).  For Visual Studio Code users, then also read [vscode.md](vscode.md).
 
 Or, if you are a [Rowley Crossworks for ARM](https://www.rowley.co.uk/arm/index.htm) user, take a look at the pico-crossworks example in [pico-demos](https://github.com/majbthrd/pico-demos).
 
diff --git a/howto/vscode.md b/howto/vscode.md
new file mode 100644
index 0000000..f713aac
--- /dev/null
+++ b/howto/vscode.md
@@ -0,0 +1,28 @@
+## pico-debug debugging with Visual Studio Code
+
+There are a few [Visual Studio Code](https://code.visualstudio.com/) (aka VS Code) examples online for the RP2040 so far.  So far, they all assume picoprobe.
+
+To adapt these from picoprobe to pico-debug, first make sure that you followed the earlier build steps and have downloaded and installed the newer pico-sdk and openocd in the howto instructions.  This is important.  The newer pico-sdk is needed to fix problems pico-sdk has with single device debugging, and the newer openocd is needed to support single device debugging.
+
+For existing Visual Studio Code examples written for picoprobe, in the launch.js file, replace this picoprobe configuration:
+
+```
+             "configFiles": [
+                 "/interface/picoprobe.cfg",
+                 "/target/rp2040.cfg"
+             ],
+```
+
+with
+
+```
+             "configFiles": [
+                 "interface/cmsis-dap.cfg",
+                 "target/rp2040-core0.cfg"
+             ],
+             "openOCDLaunchCommands": [
+                 "transport select swd",
+                 "adapter speed 4000"
+             ],
+```
+