Skip to content

doc: Add VSC instructions to the GSG guide #229

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarkusLassila merged 1 commit into from
Mar 31, 2026
Merged

doc: Add VSC instructions to the GSG guide #229

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 76 additions & 40 deletions doc/gsg_guide.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,87 +10,123 @@ Getting started
Before getting started, make sure you have a proper |NCS| development environment.
Follow the official `Getting started guide`_.

There are two options for setting up the project, depending on your preferred development environment:

* Using `nRF Connect for VS Code`_ (recommended)
Copy link
Copy Markdown
Contributor

@MarkusLassila MarkusLassila Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have to recommend this? I would change the order as we have plenty of overlay-files for which the documentation is intended for command line usage.

Copy link
Copy Markdown
Collaborator Author

@divipillai divipillai Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We recommend the end users to use VSC - https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/installation/install_ncs.html. If really needed, I can remove the word recommended but I think VSC is given priority over command line. VSC works with overlay-files as well - https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/app_dev/config_and_build/cmake/index.html#providing_cmake_options. I can include those steps (about overlay files).

Copy link
Copy Markdown
Contributor

@MarkusLassila MarkusLassila Mar 25, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to change that. But take a look on how the overlay's are discussed in the documentation and whether that aligns with this. We are giving at least come direct command line compilation commands.

Copy link
Copy Markdown
Collaborator

@trantanen trantanen Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our company wants to prefer VS Code, I guess. I'd do a compromise and keep the order of the tabs but remove "recommended". But I don't know if we can do that...

Copy link
Copy Markdown
Collaborator

@trantanen trantanen Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So do we need to change something? Or can I just merge this?

Copy link
Copy Markdown
Collaborator Author

@divipillai divipillai Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I plan to add the overlay instructions for VSC. Please wait.

Copy link
Copy Markdown
Collaborator Author

@divipillai divipillai Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have added some sentences about how to configure the variables (Kconfig, overlayfiles, etc)..

* Using the command line

Initialization
**************

This section represents alternative approaches for initializing the workspace.

Add |SM| into existing |NCS| workspace
======================================
.. tabs::

.. group-tab:: nRF Connect for VS Code

#. To install the |NCS| and its toolchain using nRF Connect for VS Code, follow `extension documentation <nRF Connect for VS Code install_>`_ or `Installing nRF Connect SDK and VS Code exercise <Devacademy VS Code exercise_>`_ on Nordic Developer Academy.
#. Open the nRF Connect extension in |VSC| by clicking its icon in the :guilabel:`Activity Bar`.
#. Click :guilabel:`Create New Application`.
#. Select the **Browse nRF Connect SDK add-on Index** option.
#. Search for the **Serial Modem** application and create the project.

.. group-tab:: Command line

.. tabs::

.. group-tab:: Add |SM| into existing |NCS| workspace

Assume you have an existing |NCS| workspace in the :file:`ncs` folder.
Assume you have an existing |NCS| workspace in the :file:`ncs` folder.

#. Navigate to the workspace folder::
#. Navigate to the workspace folder::

cd ncs
cd ncs

#. Clone |SM| repository::
#. Clone |SM| repository::

git clone https://github.com/nrfconnect/ncs-serial-modem.git
git clone https://github.com/nrfconnect/ncs-serial-modem.git

#. Set manifest path to the |SM|::
#. Set manifest path to the |SM|::

west config manifest.path ncs-serial-modem
west config manifest.path ncs-serial-modem

#. Update the |NCS| modules::
#. Update the |NCS| modules::

west update
west update

Depending on the current state of your |NCS| modules, this may take several minutes as it fetches all |NCS| modules according to the requirements of the |SM|.
Depending on the current state of your |NCS| modules, this may take several minutes as it fetches all |NCS| modules according to the requirements of the |SM|.

Initialize workspace and add |SM| from scratch
==============================================
.. group-tab:: Initialize workspace and add |SM| from scratch

Complete the following steps for initialization:
Complete the following steps for initialization:

#. To initialize the workspace::
#. To initialize the workspace::

west init -m https://github.com/nrfconnect/ncs-serial-modem --mr main ncs
west init -m https://github.com/nrfconnect/ncs-serial-modem --mr main ncs

#. Navigate to the workspace folder::
#. Navigate to the workspace folder::

cd ncs
cd ncs

#. Update the |NCS| modules::
#. Update the |NCS| modules::

west update
west update

This may take several minutes as it fetches all |NCS| modules according to the requirements of the |SM|.
This may take several minutes as it fetches all |NCS| modules according to the requirements of the |SM|.

Building and running
********************

Before building and running the application, you need to connect the development kit to your PC using a USB cable and power on the development kit.
Complete the following steps for building and running:

#. From the workspace folder, navigate to the :file:`ncs-serial-modem` folder::
.. tabs::

.. group-tab:: nRF Connect for VS Code

#. Complete the steps in the `How to build an application`_ section in the extension documentation to build the application.

You can also specify the additional configuration variables (Kconfig, DTC overlays, and extra Kconfig options) while setting up a build configuration during building the application.
See `Providing CMake options <cmake_options_>`_ for more information on setting the additional configuration variables.

#. Open the nRF Connect extension in |VSC| by clicking its icon in the :guilabel:`Activity Bar`.
#. In the extension's `Actions View`_, click on :guilabel:`Flash`.

The application is now built and flashed to the device.
You can open a serial terminal to use the application.
The default baud rate is 115200.

.. group-tab:: Command line

#. From the workspace folder, navigate to the :file:`ncs-serial-modem` folder::

cd ncs-serial-modem/app
cd ncs-serial-modem/app

#. To build the application, run the following command::
#. To build the application, run the following command::

west build -p -b nrf9151dk/nrf9151/ns
west build -p -b nrf9151dk/nrf9151/ns

To build the application with Kconfig and DTC overlays and extra Kconfig options, the following command gives an example of how they are passed as build arguments::
To build the application with Kconfig, DTC overlays, and extra Kconfig options, the following command gives an example of how they are passed as build arguments::

west build -p -b nrf9151dk/nrf9151/ns -- -DEXTRA_CONF_FILE="overlay-ppp.conf;overlay-cmux.conf" -DEXTRA_DTC_OVERLAY_FILE="overlay-external-mcu.overlay" -DCONFIG_SM_LOG_LEVEL_DBG=y
west build -p -b nrf9151dk/nrf9151/ns -- -DEXTRA_CONF_FILE="overlay-ppp.conf;overlay-cmux.conf" -DEXTRA_DTC_OVERLAY_FILE="overlay-external-mcu.overlay" -DCONFIG_SM_LOG_LEVEL_DBG=y

#. To program the application, run the following command::
#. To program the application, run the following command::

west flash
west flash

The application is now built and flashed to the device.
You can open a serial terminal to use the application.
The default baud rate is 115200.
The application is now built and flashed to the device.
You can open a serial terminal to use the application.
The default baud rate is 115200.

.. note::
.. note::

When building the |SM| application, the manifest path must point to the :file:`ncs-serial-modem` folder.
Otherwise linking will fail as drivers and libraries from |SM| will not be found.
When building the |SM| application, the manifest path must point to the :file:`ncs-serial-modem` folder.
Otherwise linking will fail as drivers and libraries from |SM| will not be found.

To check your current manifest path, run the following command anywhere in your workspace::
To check your current manifest path, run the following command anywhere in your workspace::

west config manifest.path
west config manifest.path

To set the manifest path for |SM|, run the following command::
To set the manifest path for |SM|, run the following command::

west config manifest.path ncs-serial-modem
west config manifest.path ncs-serial-modem
7 changes: 7 additions & 0 deletions doc/links.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,11 @@
.. _`+CGDCONT`: https://docs.nordicsemi.com/bundle/ref_at_commands_nrf91x1/page/REF/at_commands/packet_domain/cgdcont.html
.. _`+CGAUTH`: https://docs.nordicsemi.com/bundle/ref_at_commands_nrf91x1/page/REF/at_commands/packet_domain/cgauth.html

.. _`nRF Connect for VS Code`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/index.html
.. _`nRF Connect for VS Code install`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/get_started/quick_setup.html
.. _`How to build an application` : https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/get_started/build_app_ncs.html#how-to-build-an-application
.. _`Actions View`: https://docs.nordicsemi.com/bundle/nrf-connect-vscode/page/reference/ui_sidebar_actions.html

.. ### docs.zephyrproject.org/

.. _`Zephyr Networking`: https://docs.zephyrproject.org/latest/connectivity/networking/index.html
Expand All @@ -103,6 +108,8 @@

.. ### others

.. _`Devacademy VS Code exercise`: https://academy.nordicsemi.com/courses/nrf-connect-sdk-fundamentals/lessons/lesson-1-nrf-connect-sdk-introduction/topic/exercise-1-1/

.. _`Private addresses`: https://en.wikipedia.org/wiki/IP_address#Private_addresses

.. _`3GPP TS 27.010`: https://www.etsi.org/deliver/etsi_ts/127000_127099/127010/18.00.00_60/ts_127010v180000p.pdf
Expand Down
Loading