Overview of mmWave SDK Out of Box Demo - 18xx
===========
This is the mmWave SDK out-of-box demo lab for the IWR1843BOOST EVM.
With the accompanying online mmWave Demo Visualizer, users can specify sensing characteristics and then visualize the resulting detected objects and other real-time output information.
{{y
Users of an IWR1843BOOST EVM should first run this lab before any other lab in the mmWave Industrial Toolbox. This will enable users to gain familiarity with the sensor's capabilities as well as the various tools used across all labs in the mmWave Industrial Toolbox.
}}
# Requirements
### Required and Supported mmWave Evaluation Modules (EVM)
Quantity | Item
------------------|-----------------
1 | [IWR1843BOOST EVM](http://www.ti.com/tool/IWR1843BOOST)
### Additional Hardware Requirements
Quantity | Item | Details
---------|--------------------------|-----------------
1 | Computer | Windows 7 or 10 PC with Google Chrome Browser and TI Cloud Agent Extension installed.
1 | Micro USB Cable | Provided with the IWRXXXXBOOST board
1 | Power Supply | 5V, 3A with 2.1-mm barrel jack (center positive). The power supply can be wall adapter style or a battery pack with a USB to barrel jack cable.
### Software
Tool | Version | Download Link
----------------------------|---------------------------|--------
TI mmWave SDK | 3.5.0.4 | [Link to Latest mmWave SDK](http://software-dl.ti.com/ra-processors/esd/MMWAVE-SDK/latest/index_FDS.html) To access a previous version of the mmWave SDK scroll to the bottom of the table and click the link under "MMWAVE-SDK previous release". Repeat to continue stepping back to previous versions.
mmWave Demo Visualizer | 3.5.0 | Available online at https://dev.ti.com/gallery/view/mmwave/mmWave_Demo_Visualizer/
mmWave Industrial Toolbox | Latest | Download and install the toolbox. Go to [Using TI Resource Explorer & the mmWave Industrial Toolbox](../../../../docs/readme.html) for instructions.
Uniflash | Latest | Uniflash tool is used for flashing TI mmWave Radar devices. [Download offline tool](http://www.ti.com/tool/UNIFLASH) or use the [Cloud version](https://dev.ti.com/uniflash/#!/)
Quickstart
===========
The quickstart guide will cover setting up the EVM, flashing firmware, and running the demo.
By the end users should be able to visualize detected object data using the sensor and be able to begin evaluating different configurations and plot capabilities.
## 1. Setup the EVM for Flashing Mode
Follow the instructions for [Hardware Setup of IWRXXXXBOOST for Flashing Mode](../../../common/docs/hardware_setup/hw_setup_boost_evm_flashing.html)
## 2. Flash the EVM using Uniflash
Flash the binary listed below using UniFlash. Follow the instructions for [using UniFlash](../../../common/docs/software_setup/using_uniflash_with_mmwave.html)
BIN Name | Location
--------------------------|------------
xwr18xx_mmw_demo_isk.bin | `\mmwave_industrial_toolbox_\out_of_box_demo\` `18xx_mmwave_sdk\prebuilt_binaries\isk\xwr18xx_mmw_demo.bin`
Note: The demo source code and pre-compiled binary for the mmWave SDK out-of-box demo is available at `\mmwave_sdk_\packages\ti\demo\xwr18xx\mmw`.
For convenience, the _exact same_ pre-compiled binary is also provided within the mmWave Industrial Toolbox at the path listed in the table above.
## 3. Setup the EVM for Functional Mode
Follow the instructions for [Hardware Setup of IWRXXXXBOOST for Functional Mode](../../../common/docs/hardware_setup/hw_setup_boost_evm_functional.html)
At this point, the EVM should be powered, connected to the PC, flashed with the demo, and put in functional mode. The hardware setup is now complete.
## 4. Run the Lab
The following steps will walk through running the lab. This involves setting up the GUI to communicate with the EVM, sending a configuration to the device, and then visualizing the resulting output with the GUI.
### 1. GUI Setup
* Using Google Chrome, navigate to the following URL: [https://dev.ti.com/mmWaveDemoVisualizer](https://dev.ti.com/mmWaveDemoVisualizer)
* If prompted, follow the on-screen instructions for installing TI Cloud Agent (this is needed the first time on a new PC)
* Tip: If there are problems with installing the TI Cloud Agent, restart the PC and try again.
* In the GUI menu, select Options → Serial Port
* In the serial port window, enter the appropriate port in each of the drop down menus based on your port numbers from the [Flash the EVM](#2-flash-the-evm-using-uniflash) section
* Click on Configure to connect the GUI to the EVM. The GUI Status bar at the bottom should update with information about the two ports as well as the EVM type
### 2. Running the Demo
-----------
* On the Configure Tab, select the appropriate mmWave SDK and device from the Platform dropdown menu
* Use the available sliders to create the desired configuration.
* You can also use the presets available in the Desirable Configuration drop-down list.
* Additional details about the configuration parameters can be found in the [mmWave Demo Visualizer User Guide](http://www.ti.com/lit/pdf/swru529)
* Select the desired plots under Plot Selection (e.g. Scatter Plot, Range Azimuth Plot)
* When ready to send the configuration, click on Send Config To mmWave Device
* Click on the Plots tab to view the plots that were selected to be shown
* Move a highly reflective object in front of the EVM and see how the demo responds.
* You can use the Real Time Tuning controls shown below to adjust CFAR thresholds, Modify Field of View and enable or disable Peak grouping in real time.
This concludes the Quick Start Section
-----------
Developer's Guide
===========
* [Build the firmware from source code](#build-the-firmware-from-source-code)
* [Work with GUI source code](#work-with-gui-source-code)
* [Understand input config file](#understand-input-config-file)
Build the Firmware from Source Code
-----------
### 1. Software Requirements
Tool | Version | Download Link
----------------------------|---------------------------|--------------
TI mmWave SDK | 3.5.0.4 | [Link to Latest mmWave SDK](http://software-dl.ti.com/ra-processors/esd/MMWAVE-SDK/latest/index_FDS.html) To access a previous version of the mmWave SDK scroll to the bottom of the table and click the link under "MMWAVE-SDK previous release". Repeat to continue stepping back to previous versions.
Code Composer Studio | 8.3.1 | [Code Composer Studio v8](http://processors.wiki.ti.com/index.php/Download_CCS#Code_Composer_Studio_Version_8_Downloads)
### 2. Import Lab Project
To import the source code into your CCS workspace, CCS projects are provided for the mmWave SDK Out-of-box demo in the mmWave Industrial Toolbox.
[[b! Project Workspace
When importing projects to a workspace, a copy is created in the workspace. It is important to note that the copy in the user's workspace is the one that gets built and all modifications will only be implemented for the workspace copy. The original project downloaded in mmWave Industrial Toolbox is not modified.
]]
- Start CCS and setup workspace as desired.
- Import the project(s) specified below to CCS. See instructions for importing [here](../../../../docs/readme.html#import-ccs-projects-from-the-mmwave-industrial-toolbox-into-code-composer-studio)
Project Name | Location in Industrial Toolbox
---------------------------|-----------------------------
mmwave_sdk_18xx_dss | Do not import. Automatically imported with mss project.
mmwave_sdk_18xx_mss | `\mmwave_industrial_toolbox_\out_of_box_demo\18xx_mmwave_sdk\src`
- Verify that the import occurred without error: in CCS Project Explorer both **mmwave_sdk_18xx_dss** and **mmwave_sdk_18xx_mss** projects should appear.
[[r! Error during Import to IDE
If an error occurs, check that the software dependencies listed above have been installed. Errors will occur if necessary files are not installed in the correct location for importing.
]]
### 3. Build the Lab
1. Select the **mmwave_sdk_18xx_mss** so it is highlighted. Right click on the project and select **Rebuild Project**. The DSS project will automatically build first and then the MSS project.
2. On successful build, the following should appear:
* In mmwave_sdk18xx_dss → isk, **xwr18xx_mmw_dss.xe674** (this is the C67x binary used for CCS debug mode)
* In mmwave_sdk18xx_mss → isk, **xwr18xx_mmw_mss.xer4f** (this is the Cortex R4F binary used for CCS debug mode) and **xwr18xx_mmw_demo.bin** (this is the flashable binary used for deployment mode)
{{y Selecting Rebuild instead of Build ensures that the project is always re-compiled. This is especially important in case the previous build failed with errors.}}
[[r! Build Fails with Errors
If the build fails with errors, please ensure that all the software requirements are installed as listed above and in the mmWave SDK release notes.
]]
[[b! Note
As mentioned in the [Quickstart](#quickstart) section, pre-built binary files, both debug and deployment binaries are provided in the pre-compiled directory of the lab.
]]
### 4. Execute the Compiled Lab
There are two ways to execute the compiled code on the EVM:
* **Deployment mode**: In this mode, the EVM boots autonomously from flash and starts running the bin image
* Use the **xwr18xx_mmw_demo.bin** found at `\mmwave_sdk_18xx_mss\isk\` and follow the same process in the [Quickstart](#quickstart) section except flash this binary instead.
* **Debug mode**: This mode is is used for downloading and running the executable from CCS. This mode enables JTAG connection with CCS while the lab is running and is useful during development and debugging.
* Follow the [CCS Debug Mode Guide](../../../common/docs/software_setup/using_ccs_debug.html), using the binaries listed below.
* After CCS Debug mode is setup, launch the visualizer and load a config as described in the [Run the Lab section of the Quickstart](#4-run-the-lab)
Debug binary | Location | Connect and load to
---------------|----------|----------------------
xwr18xx_mmw_mss.xer4f | `\mmwave_sdk_18xx_mss\isk\` | Cortex_R4_0
xwr18xx_mmw_dss.xe674 | `\mmwave_sdk_18xx_dss\isk\` | C674X_0
### 5. Output from mmWave Demo Visualizer and Output using DCA1000EVM
The mmWave Demo Visualizer is used to visualize processed output data from the mmWave radar device. This processed output data can be saved in binary form to a .DAT file. Additionally, raw ADC data can be saved for offline processing using the [DCA1000 EVM](https://www.ti.com/tool/DCA1000EVM).
To learn more about the structure of this output data please refer to the following resources:
[[b! Output Data versus Raw ADC Data
Output data refers to point cloud data (x,y,z,v). Raw ADC data refers to digitally sampled sensor data.
]]
* Output Data Structure Information:
* `\packages\ti\demo\xwr18xx\mmw\docs\doxygen\html`
* How to use the [DCA100EVM](https://www.ti.com/tool/DCA1000EVM) for raw data capture:
* `\docs\mmwave_sdk_user_guide.pdf` Section 3.3.2 mmWave Demo with LVDS-Based Instrumentation
* Parsing Script Information for mmWave Demo Visualizer
* `\docs\mmwave_sdk_user_guide.pdf` Section 3.3.1 mmWave Demo - Advanced GUI Options
* Parsing Script Location for mmWave Demo Visualizer and [DCA100EVM](https://www.ti.com/tool/DCA1000EVM) for raw data capture:
* `\packages\ti\demo\parser_scripts`
-----------
Work with GUI source code
-----------
This demo uses the mmWave Demo Visualizer which was created using GUI Composer. Users can import the GUI source code into the cloud version of GUI Composer to view and modify the source code as needed.
1. Open the mmWave Demo Visualizer: https://dev.ti.com/gallery/view/mmwave/mmWave_Demo_Visualizer/
2. In the upper top menu, go to Help → Download or Clone Visualizer
3. Click on the import to GUI Composer icon.
4. The mmWave_Demo_Visualizer project and its source code should now be visible within GUI composer.
A quick overview of the mmWave Demo Visualizer specific files follows:
* mmWave.js: Main file that communicates with the GUI composer framework, communicates to the mmWave device using the configured COM ports, processes GUI-generated actions, and plots the data generated by the mmWave device
* input_validations.js: validates the CLI configuration before it is sent to the mmWave device
* dynamic_tuning.js: implementation of "real time tuning" tab and "advanced commands" tab
* input.js: Handles all the backend computations behind the CONFIGURE tab
* Index.gui: Auto-generated file that handles the layout of the Visualizer app
* Helper utilities: Delaunay.js, fft.js, math.js, math_griddata.js, and myutil.js
For help with GUI Composer refer to:
* [GUI Composer Getting Started Guide](https://dev.ti.com/gc/designer/help/Tutorials/GettingStarted/index.html)
* [GUI Composer User's Guide](https://dev.ti.com/gc/designer/help/UsersGuide/index.html)
-----------
Understand Input Config File
-----------
With the mmWave Demo Visualizer, users can generate and send a cfg file or load an existing cfg file.
The commands and parameters contained in the cfg file are detailed in: "Section 3. 4. Configuration (.cfg) File Format" of the [mmWave SDK user's guide](http://software-dl.ti.com/ra-processors/esd/MMWAVE-SDK/latest/exports/mmwave_sdk_user_guide.pdf).
-----------
Need More Help?
===========
* Additional resources in the documentation of the mmWave SDK:
* mmWave SDK Module Doc located at `/docs/mmwave_sdk_module_documentation.html`
* mmWave SDK User's Guide located at `/docs/mmwave_sdk_user_guide.pdf`
* mmWave SDK Release Notes located at `/docs/mmwave_sdk_release_notes.pdf`
* Find answers to common questions on [mmWave E2E FAQ](https://e2e.ti.com/support/sensor/mmwave_sensors/w/wiki)
* Search for your issue or post a new question on the [mmWave E2E forum](https://e2e.ti.com/support/sensor/mmwave_sensors/f/1023)