README (4355B)
1 gp24 2 ============================================================================== 3 Example project on how to lay out a small, multi-language embedded codebase for 4 controlling a greenpower racecar. 5 6 gp24: Motivation 7 ============================================================================== 8 A greenpower car consists of the following critical systems: 9 - Batteries : We need to store energy to do anything 10 - Motors : We need to move the car 11 - Controls : We need to accept inputs from the driver (i.e. throttle) 12 - Heads-Up Display : We need to show things to the driver (i.e. battery level) 13 14 Optionally, it may also contain the following systems: 15 - Telemetry : We might want to log debug and status information when running 16 17 Fundamentally, greenpower is about optimising your battery usage. You want to 18 minimise the work the motors have to do to accelerate you to speed and keep 19 you there, and want to maximise the time the motors can keep you at speed for. 20 21 To do that, we need to minimise the amount of work done by the control system 22 beyond that which is absolutely necessary. That means minimal processing on any 23 inputs taken from the driver, minimal processing on any inputs taken from the 24 car itself, and a minimal GUI to display only the neccessary information. 25 26 Alongside this goal of minimising work, however, is the need to know how the 27 car is performing. Both for debugging failures, as well as helping with future 28 development, we need to at least log the state of the car at regular intervals 29 to an SD card (or other removable storage). If the power budget allows, there 30 is also the option of using remote telemetry from the car to the pit, to store 31 telemetry on the receiving device. 32 33 gp24: Architecture 34 ============================================================================== 35 We want to have the ability to target a variety of devices, to potentially 36 do initial testing and prototyping on a more ergonomic development board, and 37 then refine the result to run on a lower-power board when integrated into the 38 final car. To achieve this goal, we need to abstract away from concrete 39 microcontrollers as much as possible. To help with this, we write in mainly 40 C/C++, with platform-specific assembly helpers and a hardware abstraction 41 layer where necessary. 42 43 Thus, for each platform that the project targets and builds for, we have 44 the following: 45 46 ``` 47 <target>.lds - platform-specific linker script 48 <target>/plat.S - platform-specific assembly code, used by HAL 49 <target>/hal.c - platform-specific hardware abstraction layer 50 <target>/*.c - additional platform-specific C source files 51 <target>/*.h - additional platform-specific C header files 52 ``` 53 54 This HAL is then used by the platform-independent portion of the code, 55 located under `src/*.{cpp,hpp,h}`. This is where the bulk of the code exists, 56 including the main loop, the graphics code, and the telemetry code. 57 58 The top-level source file to start from is `src/gp24.cpp`, which includes all 59 further source files in a "unity build" fashion. This approach allows precise 60 control over the placement of any static variables, control over the order of 61 definition of symbols, avoids multiple rounds of header file parsing, as well 62 as cleaning up and simplifying the build script. 63 64 Any third-party dependencies, such as header-only libraries, or hardware 65 definition headers (e.g. defining memory-mapped addresses), live under the 66 `dep/` directory. These may be platform-dependent, and if so their use must 67 be guarded by the relevant `#ifdef` guards. 68 69 Any documentation is kept under `docs/`. 70 71 gp24: Building 72 ============================================================================== 73 To build the project, there exists `build.sh`. When ran without any arguments, 74 it will build for the default platform. To specify what platform to build for, 75 it is necessary to pass a commandline argument, as follows: 76 77 ``` 78 $ ./build.sh <platform> # see `build.sh` for available values for <platform> 79 ``` 80 81 Building the project results in an elf file, `bin/gp24.elf`. This is useful 82 when debugging, to get symbol information to your debugger of choice. For 83 flashing onto the target platform, however, there are also `bin/gp24.bin` and 84 `bin/gp24.hex` that are generated. A symbol map is also generated for debugging 85 purposes, and can be found at `bin/gp24.map`. 86 87 To clean the project, there exists `clean.sh`.