diff options
| -rw-r--r-- | robot/readme.md | 90 |
1 files changed, 84 insertions, 6 deletions
diff --git a/robot/readme.md b/robot/readme.md index 5e7efb6..b025f7d 100644 --- a/robot/readme.md +++ b/robot/readme.md @@ -1,10 +1,88 @@ # robot code -dit is de submap voor alle code die op de robot zelf draait +this is the subdirectory for all code that runs on the 3pi robot -## make gedoe +## make + +the makefile in this directory works the same as a regular makefile, with the +exception of the `make flash` command. + +to upload the compiled robot executable, you need to change the com port +specified in the makefile in this directory (line that says `PORT ?= +/dev/ttyACMx`). for windows this should be changed to `PORT ?= COMx`, where x +is the number of the 'programming' com port on the programmer. this will +probably change every time you re-plug the programmer, so you should try every +com port until it uploads successfully. you can find available com ports in +device manager on windows, or by running `ls /dev/ttyACM*` on linux. once the +com port is configured, run `make flash` to upload the executable and +automatically reboot the robot. + +## module hierarchy + +the software is divided into seperate 'modules' for maintenance, testing and +debugging purposes. the sizes of the blocks in the following diagram are a bit +misleading, as some of these blocks are mostly organizational and form more of +a software 'skeleton', while the 'maze' and 'warehouse' modules provide the +majority of the control logic. + +``` +┌──────────────────────────────────────────────────────────────────────┐ +│ "Hypervisor" │ +└────────┬───────────────────┬──────────────────┬───────────────┬──────┘ +┌────────┴─────────┐┌────────┴───────┐┌─────────┴────────┐┌─────┴──────┐ +│ PC communication ││ Error handling ││ I/O Read & Write ││ Mode logic │ +└──────────────────┘└────────────────┘└──────────────────┘└─────┬──────┘ + ┌──────────┬──────────────┬───────────────┤ + ┌───┴──┐┌──────┴────┐┌────────┴───────┐┌──────┴──────┐ + *modes* -> │ Maze ││ Warehouse ││ Emergency stop ││ Calibration │ + └──────┘└───────────┘└────────────────┘└─────────────┘ +``` + +this diagram roughly describes how different parts of the robot software are +called. most of these modules can talk to each other (e.g. the maze module +sending an error code to the error handling module, which then forwards it to +pc communication). here's a quick run-down of all modules and what they're +supposed to do: + +|module |internal name|purpose| +|----------------|-------------|-| +|hypervisor |`hypervisor `|backbone of all other modules; stores global variables; controls when other modules run| +|pc communication|`sercomm `|reads and parses incoming serial data; sends all data in the message buffer| +|error handling |`errcatch `|receives error codes; controls how errors are handled| +|i/o read & write|`io `|reads all inputs to global state; writes all outputs| +|mode logic |`model `|executes the appropriate module for current mode| +|maze |`mode_maze `|controls robot during maze portion of map; hands off control to warehouse module| +|warehouse |`mode_grid `|controls robot during warehouse portion of map; hands off control to maze module| +|emergency stop |`mode_halt `|stops all execution until emergency mode is reset by software or user| +|calibration |`mode_calb `|find line by turning on own axis if lost| + +## some standards + +this list will probably get updated from time to time: + +- modules shouldn't create any global state variables, they should use `static` + variables instead. +- modules are run cyclically, so they shouldn't take more than + `W2_MAX_MODULE_CYCLE_MS` to execute (this is an arbitrary number, and may be + changed). +- documentation comments should follow the [javadoc-style doxygen + format](https://wiki.scilab.org/Doxygen%20documentation%20Examples) and be + placed in header (.h) files if possible. this only applies to public members + (e.g. no local variables or module-internal code). +- code style is mostly handled by `clang-format` and `clang-tidy`, but you + should still follow these naming conventions (`<angle brackets>` indicate + placeholders): + |symbol type|name|example| + |-|-|-| + |function|`w2_<module>_<name>`|`w2_errcatch_pushcode`; `w2_sercomm_sendraw`| + |variable|`g_w2_<name>`|`g_w2_inputs`; `g_w2_current_mode`| + |constant|`W2_<NAME>`|`W2_MAX_MODULE_CYCLE_MS`; `W2_SERIAL_BAUD`| + |struct|`w2_s_<name>`|`w2_s_input_data`; `w2_s_output_data`| + |enum|`w2_e_<name>`|`w2_e_errorcodes`; `w2_e_serial_commands`| + + this again only applies to public members. local variables should still have + short descriptive names, but shouldn't be prefixed with `w2_*`. +- arbitrary numbers should be aliased to `#define` statements or `enum`s if + part of a series. +- constants should be placed in `consts.h` -om de code te uploaden naar de robot moet je de juiste com-poort instellen in -de makefile in deze map (regel waar `PORT ?= /dev/ttyACM0` staat). deze kun je -waarschijnlijk vinden in apparaatbeheer op windows (bijv. `PORT ?= COM4`). -daarna kun je `make flash` uitvoeren om de code te uploaden |