Merge pull request #6 from project-ocre/updating_quickstart_guide

Added virtual environment steps, as well as a success screenshot and …

Author: gonzolively

docs/quickstart/firmware/hardware.md

@@ -22,30 +22,27 @@ Complete the [Install dependencies](https://docs.zephyrproject.org/3.7.0/develop
 {: .note}
 Currently the Ocre runtime is built on Zephyr `3.7.0`. As a result, the links in the above section reference `v3.7.0` documentation and not the *latest* documentation. It is advised to follow the links in this guide to ensure compatibility with your device.
 
-### **2. Install WEST**
-
-Install the [west](https://docs.zephyrproject.org/latest/develop/west/index.html) CLI tool, which is needed to build, run and manage Zephyr applications.
+### **2. Create a Virtual Python Environment (venv)**
+Create a [Python virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) (venv) to isolate your Python project dependencies.
 
 ```
-pip install west
+mkdir runtime && cd runtime
+python3 -m venv .venv
+source .venv/bin/activate
 ```
 
-{: .note}
-We recommend using a Python virtual environment like [venv](https://docs.python.org/3/library/venv.html) to help manage pip dependencies for this project.
+{: .highlight}
+You *may* need to install the `python3-venv` package (or equivalent) on your host system beforehand.
 
-### **3. Initialize the workspace**
+### **3. Install WEST**
 
-Next, we will prepare the Zephyr workspace and checkout the project code.
+Install the [west](https://docs.zephyrproject.org/latest/develop/west/index.html) CLI tool, which is needed to build, run and manage Zephyr applications.
 
-First, create the `runtime` directory in the location of your choosing.
 ```
-mkdir runtime
+pip install west
 ```
-Next, cd to the `runtime` directory.
 
-```
-cd runtime
-```
+### **4. Initialize the workspace**
 
 Now, initialize the `ocre-runtime` repo.
 ```
@@ -58,35 +55,41 @@ Lastly, update the repo with the `west` utility.
 west update
 ```
 
-### **4. Install Additional Zephyr (pip) requirements**
+{: .note}
+`west update` may take 5-10 minutes as it pulls all Zephyr Project board sources.
+
+### **5. Install Additional Zephyr (pip) requirements**
 
 In order to build the Ocre runtime properly, you'll need to install a few remaining requirements for Zephyr.
 
 ```
 pip install -r zephyr/scripts/requirements.txt
 ```
 
-### **5. Build the Ocre Runtime**
+### **6. Build the Ocre Runtime**
 
-To build and flash for a physical device, follow these steps:
+Build the application for your specific board, replacing `BOARD_NAME` with your board's name:
+```
+west build -b BOARD_NAME ./application -d build -- -DMODULE_EXT_ROOT=`pwd`/application
+```
 
-1. Connect your board to your computer.
+{: .note}
+ See the [Board Support](../../../board-support) section in your docs to see if your board is currently supported. If your board is listed, check the "Building and Flashing the Ocre Runtime" section for your `BOARD_NAME` and other relevant info for flashing the Ocre Runtime to your particular device.
 
-2. Build the application for your specific board. Replace `BOARD_NAME` with your board's name:
-   ```
-   west build -b BOARD_NAME ./application -d build -- -DMODULE_EXT_ROOT=`pwd`/application
-   ```
+### **7. Flash the Ocre Runtime to Your Device**
 
-{: .note}
-You can also run the **West Build** task directly from the **Ocre Workspace** file as defined in the [Setting Up Your Development Environment](../dev-environment) section. If you do, be sure to select your board name as your build target. See the [Board Support](../../../board-support) section in your docs to see if your board is currently supported. 
+To flash the Ocre Runtime to your device follow these steps:
 
-### **6. Flash the Ocre Runtime to Your Device**
+1. Connect your board to your computer.
+2. Open your [serial console](../../quickstart/prerequisites/serial-console/index.md), and connect to your board.
 1. Flash the application to your device:
    ```
    west flash
    ```
 
-After flashing, restart/reset your board to run the application.
+After flashing, restart/reset your board to run the application. If successful, you should see the following output on your console:
+
+![](../success.png)
 
 ---
 

docs/quickstart/firmware/simulated.md

@@ -31,30 +31,27 @@ Complete the [Install dependencies](https://docs.zephyrproject.org/3.7.0/develop
 {: .note}
 Currently the Ocre runtime is built on Zephyr `3.7.0`. As a result, the links in the above section reference `v3.7.0` documentation and not the *latest* documentation. It is advised to follow the links in this guide to ensure compatibility with your device.
 
-### **2. Install WEST**
-
-Install the [west](https://docs.zephyrproject.org/latest/develop/west/index.html) CLI tool, which is needed to build, run and manage Zephyr applications.
+### **2. Create a Virtual Python Environment (venv)**
+Create a [Python virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) (venv) to isolate your Python project dependencies.
 
 ```
-pip install west
+mkdir runtime && cd runtime
+python3 -m venv .venv
+source .venv/bin/activate
 ```
 
-{: .note}
-We recommend using a Python virtual environment like [venv](https://docs.python.org/3/library/venv.html) to help manage pip dependencies for this project.
+{: .highlight}
+You *may* need to install the `python3-venv` package (or equivalent) on your host system beforehand.
 
-### **3. Initialize the workspace**
+### **3. Install WEST**
 
-Next, we will prepare the Zephyr workspace and checkout the project code.
+Install the [west](https://docs.zephyrproject.org/latest/develop/west/index.html) CLI tool, which is needed to build, run and manage Zephyr applications.
 
-First, create the `runtime` directory in the location of your choosing.
 ```
-mkdir runtime
+pip install west
 ```
-Next, cd to the `runtime` directory.
 
-```
-cd runtime
-```
+### **4. Initialize the workspace**
 
 Now, initialize the `ocre-runtime` repo.
 ```
@@ -67,15 +64,18 @@ Lastly, update the repo with the `west` utility.
 west update
 ```
 
-### **4. Install Additional Zephyr (pip) requirements**
+{: .note}
+`west update` may take 5-10 minutes as it pulls all Zephyr Project board sources.
+
+### **5. Install Additional Zephyr (pip) requirements**
 
 In order to build the Ocre runtime properly, you'll need to install a few remaining requirements for Zephyr.
 
 ```
 pip install -r zephyr/scripts/requirements.txt
 ```
 
-### **5. Build the application**
+### **6. Build the application**
 
 The following will build the firmware for the *virtual*, `native_sim` target which will allow you to run the Ocre runtime on a simulated device, rather than a physical board.
 ```
@@ -85,9 +85,13 @@ west build -b native_sim ./application -d build -- -DMODULE_EXT_ROOT=`pwd`/appli
 {: .note}
 You can also run the **West Build** task directly from the **Ocre Workspace** file as defined in the [Setting Up Your Development Environment](../dev-environment) section. If you do, be sure to select `native_sim` as your build target. 
 
-### **6. Run the application**
+### **7. Run the application**
 
 To run the application, simply run the following command:
 ```
 ./build/zephyr/zephyr.exe
-```
+```
+
+If successful, you should see the following output:
+
+![](../success.png)