RoverCore-S Documentation

Transcription

1 RoverCore-S Documentation Release Khalil A. Estell Jan 11, 2019

2

3 Contents 1 Quick Links Getting Started Getting Started Prerequisites Prerequisites For Windows Installation Building and Loading Hello World Application Building and Loading FreeRTOS Project Creating your own Project Understanding The Framework Layout File Hierarchy Folder: firmware Folder: firmware/<application>/l5_application Folder: firmware/<application>/l5_assembly Folder: <applications>/build/bin Folder: <application>/build/_can_dbc Folder: <application>/build/obj Folder: firmware/lib Folder: firmware/lib/l%d_%s Guides Debugging with OpenOCD and GDB Prerequisites Step 0: Installing OpenOCD Step 1: Solder JTAG Headers to SJOne Step 2: Connecting J-Link to SJOne Step 3: Run OpenOCD Step 5: Run GDB Unit Testing Unit Testing Tools Files in test folder Compiling and Running Tests Created additional unit tests Stubbing out and Spying on Function calls using FFF.h framework Telemetry: Embedded Runtime Monitoring and Tuning Setting up Telemetry Using Telemetry i

4 1.2.4 Press Next To Get Started About Copyrights Press Next To Get Started 13 ii

5 CHAPTER 1 Quick Links Get Started Guides API Reference Hardware Reference 1.1 Getting Started Getting Started Prerequisites Need a running version of Ubuntu LTS or above, or Mac OS X (OS X Yosemite and above), or Windows 10 with WSL installed. You must also have the following pre-installed: Python 2.7+ Default installed on WSL, Ubuntu and Mac OS X 1

6 Git make Default installed on Mac OS X To install on WSL & Ubuntu run sudo apt install git-all Default installed on WSL, Ubuntu On Mac OSX this is installed after you run xcode-select --install If you are running Mac OS X you will need to install the xcode command line tools prior to running the setup. xcode-select --install. After the xcode tools are finished installing, follow the instructions below Prerequisites For Windows Note: this is for Windows build or later 1. Open PowerShell as Administrator and run Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux 2. Restart computer when prompted. 3. Open Windows Store and choose Ubuntu as Linux distro 4. Select Get Ubuntu ( If you get any errors go here: 5. After download completes select Launch (a) Create UNIX user account (b) If you get any errors go here: After this point, you should be able to run bash from the start menu Installation Step 0 Clone the repository git clone Step 1 Change directory into SJSU-Dev cd SJSU-Dev Step 2 Run setup script../setup Note: This will download and install the gcc-arm binaries, hyperload, telemetry locally to the repo. It will also generate the environment variables file and link the makefile and environment file to all of the default folders. 2 Chapter 1. Quick Links

7 Step 3 Edit the env.sh script. Change the line SJDEV=/dev/ttyUSB0 to equal what you have on your system. How to find your serial device on Ubuntu You probably do not have to change anything. If no other devices are connected to your machine, then it will be /dev/ttyusb0. It is recommended to keep it at this value, because when you add more devices, it will increment to /dev/ttyusb1. Once you remove your devices and replace them, the value will reset. How to find your serial device on Mac OS X 1. Remove the SJ-One from your computer if it is connected. 2. List the files in the /dev folder by running the following ls /dev/. 3. Plug it into your computer and run ls /dev/. 4. Observe the new file that was created. 5. On mac, the path should look something like the following /dev/tty.cumodemfd If so, change the line in env.sh to that file path from SJDEV=/dev/ttyUSB0 -> SJDEV=/dev/ tty. How to find your serial device on Windows Linux Subsystem On Windows it should be /dev/ttys3. Check your device manager to see what number COM device your device. The number after COM is the number after the S in the /dev/ttys string. That is your device. Replace the line SJDEV=/dev/ttyUSB0 -> SJDEV=/dev/ttyS Building and Loading Hello World Application Step 0 From the root of the repository cd firmware/starter Step 1 Source the env.sh. You only need to do this once for each terminal session. After sourcing, the necessary environment variables will be added to your shell. source env.sh Step 2 Run make build within the Starter folder to compile it into a HEX file located in the bin folder. make build Note: use the --help argument to get additional information on how to use the build script. Step 3 To load the hex file into your SJ-One, run the following make command: make flash Note: If you run this command without first building, this command will build your project and then flash it. So you can skip the step above if you like Getting Started 3

8 Note: If the device port of your SJOne did not appear as the device set in your env.sh file, then run make flash SJDEV=<PATH-TO-YOUR-PORT> and that will change your port path for that instant. Step 4 To view serial output, and interact with the board, run the following make command: make telemetry Note: The interface will pop up in your default browser on launch. If this does not occur you will need to enter the web address into your browser s address bar and load it. Step 5 Done!! Building and Loading FreeRTOS Project Instructions are the same as Starter, but you need to enter the firmware/freertos folder and run make from there Creating your own Project Copy and rename the FreeRTOS, Starter or any of the other template folders to any place in your computer to make a new project Understanding The Framework Layout File Hierarchy firmware Starter L5_Application examples FreeRTOS L5_Application Telemetry L5_Application periodic_scheduler Assembly L5_Assembly CPPFreeRTOS L5_Application periodic_scheduler lib _can_dbc L0_LowLevel source L1_FreeRTOS hooks include MemMang portable src trace (continues on next page) 4 Chapter 1. Quick Links

9 L2_Drivers base src L3_Utils src tlm L4_IO fat src wireless L5_HighLevel examples periodic_scheduler source L6_Testing newlib (continued from previous page) Folder: firmware This folder is meant to hold the firmware applications you make. The default applications are: Starter: Template for simple single-threaded applications. (CMPE 30) FreeRTOS: Template FreeRTOS application. (CMPE 127/146/243/244) CPPFreeRTOS: Template FreeRTOS application. (CMPE 127/146/243/244) Telemetry: Template program to demonstrate usage of Telemetry and FreeRTOS. (CMPE 127/146/243/244) Assembly: Template application for building simple ARM assembly programs (CMPE 102) Unittest: Template unit testing application. (CMPE 146/146/243/244) Folder: firmware/<application>/l5_application The L5_Application folder holds the main.cpp file and other application layer files Folder: firmware/<application>/l5_assembly The L5_Assembly folder holds the main.s ARM assembly template program Folder: <applications>/build/bin This folder holds the executables that can be loaded into the SJOne board.hex. It also holds the disassembly file.lst, linker file.map and the Executable and Linkable Format.elf file Folder: <application>/build/_can_dbc The _can_dbc folder holds the CAN message description files and header generator Getting Started 5

10 Folder: <application>/build/obj This folder holds object files created during the compilation stage of building. They are then all linked together to create an.elf file afterwards. The last phase converts the.elf to a.hex file to be loaded into SJ-One s flash memory Folder: firmware/lib This folder holds the core firmware files for the SJ-One file, such as abstractions for using GPIO, I2C, UART, Interrupts, etc Folder: firmware/lib/l%d_%s The folders that start with L<some number>_<some folder name> are kind of self explanatory as to what they hold. For example, L1_FreeRTOS holds files pertaining to FreeRTOS and the FreeRTOS port files. L2_Drivers are device drivers and so on and so forth. 1.2 Guides Debugging with OpenOCD and GDB This tutorial will use HelloWorld as an example. But this will work for any application you build Prerequisites The official supported JTAG probes for the SJOne board is the SEGGER J-LINK mini EDU. Any other J-Link device will work with no modifications to the sjone.cfg file. Otherwise, change the interface/source to the appropriate adapter Step 0: Installing OpenOCD OpenOCD was installed when you ran the initial./setup script if you are running Linux or WSL. If you are running OS X, install manually Step 1: Solder JTAG Headers to SJOne Do as the title says if you haven t already Step 2: Connecting J-Link to SJOne Connect jumpers from the GND, TDI, TMS, TCK, and TDO pins on the J-Link to the SJOne s JTAG headers. Danger: DOUBLE AND TRIPLE CHECK THAT YOUR CONNECTIONS! The SJOne costs $80 and the BusBaster costs $35! Thats $115 down the drain if your burn them out! 6 Chapter 1. Quick Links

11 Step 3: Run OpenOCD Run: # If you used make install openocd -f./tools/openocd/sjone.cfg Tip: Successful output is the following: Info : clock speed 100 khz Info : JTAG tap: lpc17xx.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x4) Info : lpc17xx.cpu: hardware has 6 breakpoints, 4 watchpoints Error: If you see the following message: Error: JTAG-DP STICKY ERROR Info : DAP transaction stalled (WAIT) - slowing down Error: Timeout during WAIT recovery Error: Debug regions are unpowered, an unexpected reset might have happened Then the SJOne board is being held in a RESET state. To fix this, either by power cycling the SJOne board or by deassert the RTS and DTR signals through GTKTerm. Error: If you see your terminal get spammed with this: Error: JTAG-DP STICKY ERROR Error: Invalid ACK (7) in DAP response Error: JTAG-DP STICKY ERROR Error: Could not initialize the debug port Then its a good chance that one of your pins is not connected Step 5: Run GDB Open another terminal and run the following command in the firmware/default/ folder. arm-none-eabi-gdb -ex "target remote :3333" bin/firmware.elf Tip: You can run arm-none-eabi-gdb without arguments and use the following gdb commands file bin/ firmware.elf then target remote :3333 in the gdb command line interface to get the same effect as the above command. At this point the SJOne board has been halted. You should be able to add breakpoints to the program at this point and step through the code. At this point you will not see any source code. Do the following in the gdb command line interface: >>> break main >>> continue 1.2. Guides 7

12 Tip: Don t use the typical run command to start the code. It is already started in the firmware. Also, run does not exist when using target remote :3333 to OpenOCD. It exists with target extended-remote :3333, but causes issues... just don t use it OK. At this point you should see the source code of your main.cpp show up. Now you can step through your code and set breakpoints using step, next, finish and continue, break, etc. For a gdb cheat sheet, see this PDF: Error: If your board keeps restarting, this is due to the Watchdog not getting fed. Although, this shouldn t happen if you ran step 0 correctly. If you do a build spotless and build your project again with the -d flag, and this still does not work, then as a last resort, go into the lpc_sys.c file and comment out the enable_watch_dog() function call Unit Testing Unit Testing Tools To unit test we support CGreens and Catch along with the FFF.h (fake function framework). CGreen must be installed globally your system for the makefile to work Files in test folder Within the test folder, there will be a folder named simple-test which contains the following: makefile: for building the tests test.cpp: a Catch unit test example. cgreen-test.cpp: is a CGreen test example. test-files.list: a new line delimited list of files to be included in your test Compiling and Running Tests Enter the simple-test folder and run make to compile and run the Catch unit test and make cgreen to compile and run the CGreen unit test file Created additional unit tests Copy the simple-test folder and edit the files within to make a new test. Do not move the folder out of the test directory of the application Stubbing out and Spying on Function calls using FFF.h framework In your source, prefix the function you want to test with the following attribute ((weak)). This will make it a weak function that can be overridden with another definition of the same function. Within your test files you can include the following to create a function stub/spy: 8 Chapter 1. Quick Links

13 FAKE_VOID_FUNC(functionToStubAndSpyOn, bool); /*... */ functiontostubandspyon.custom_fake = []() { printf("custom function"); }; See more here Telemetry: Embedded Runtime Monitoring and Tuning Wikipedia: Telemetry is an automated communications process by which measurements and other data are collected at remote or inaccessible points and transmitted to receiving equipment for monitoring. Telemetry is another means of testing your firmware. Unit test are useful for testing your code s logic and making sure the behavior of your code operates as intended. A debugger allows you step through your code one line at a time, inspecting variables to see when adverse behavior arises in your firmware. Telemetry, more or less, is a means of feeding back information to the user about the current state of the firmware during runtime Setting up Telemetry Telemetry was setup when you ran the initial./setup script Using Telemetry Step 1 Run make telemetry in your firmware project directory. It should open up a webpage in your browser. You should see the following: Step 2 Connect your SJOne Board to your computer Guides 9

14 Step 3 Press the Refresh Devices button to check your system for serial devices. Step 4 Press the Connect button to connect to the serial device. At this point, you should see the serial output of the SJOne board being written to the Serial Output textarea. If Telemetry is running on the SJOne, then a table will be generated in the Telemetry Feedback area. 10 Chapter 1. Quick Links

15 1.2.4 Press Next To Get Started 1.3 About Warning: This section is not complete 1.4 Copyrights Warning: This section is not complete 1.3. About 11

16 12 Chapter 1. Quick Links

17 CHAPTER 2 Press Next To Get Started 13