aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorlonkaars <loek@pipeframe.xyz>2022-05-09 22:27:03 +0200
committerlonkaars <loek@pipeframe.xyz>2022-05-09 22:27:03 +0200
commitd00e0f20cbc214b6c7c3221f05f79c78ba7b9de3 (patch)
tree8305e4fae39ef73d6ce668077c363580abe02d0f
parent32237bc52d1dd69d60dda75ddc29bb31ce165c83 (diff)
added summary and todo for modules0.0.1
-rw-r--r--robot/readme.md152
1 files changed, 142 insertions, 10 deletions
diff --git a/robot/readme.md b/robot/readme.md
index 998c8b1..fa5774c 100644
--- a/robot/readme.md
+++ b/robot/readme.md
@@ -19,11 +19,11 @@ 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.
+the software is divided into seperate 'modules' for organizational,
+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 actual control logic.
```
┌──────────────────────────────────────────────────────────────────────┐
@@ -39,10 +39,11 @@ majority of the control logic.
```
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:
+called. most of these modules can talk to each other using functions exposed by
+the modules themselves (e.g. the maze module sending an error code to the error
+handling module, which then both handles the error and forwards it to pc
+communication for logging purposes). here's a quick run-down of all modules and
+what they're supposed to do:
|module |internal name|purpose|
|----------------|-------------|-|
@@ -85,5 +86,136 @@ this list will probably get updated from time to time:
- arbitrary numbers should be aliased to `#define` statements or `enum`s if
part of a series.
- general constants should be placed in `consts.h`
-- run `make format` as a seperate commit in case of breaking changes
+
+## todo
+
+global todo:
+
+- [ ] add test/simulation mode for wet floor (spinning)
+- [ ] add a manual control mode
+- [ ] start robot in calibration mode
+- [ ] assume robot starts in maze
+- [ ] maze-grid transition detection in seperate file (used by grid and maze
+ mode)
+- [ ] clear global timer at start of cycle instead of just for mode selection
+ module (for last ping time measurement)
+- [ ] calibrate (line-detecting) light sensors in setup.c, or manually by
+ placing the robot and pressing a button
+
+### hypervisor
+
+the hypervisor executes all other modules, and measures execution time. it also
+provides all other modules with a central place for defining global variables.
+
+### pc communication
+
+> this mode can't be implemented until the pc-communication protocol spec is
+> finished
+
+the pc communication module sends messages in a binary format over the serial
+connection provided by the wixel modules. this module should also send a 'ping'
+command each cycle to check if the connection is still intact. the pc will also
+periodically send ping, and various other commands which this module will have
+to act on accordingly.
+
+### error handling
+
+the error handling module (a) provides functions for other modules to report
+errors, and (b) handles errors accordingly.
+
+- [ ] create an error `struct` that holds:
+ - [ ] error code
+ - [ ] message length
+ - [ ] message contents
+- [ ] create a global error ring buffer with an appropriate size that holds
+ error messages
+- [ ] handle errors in the error buffer, referencing the functional
+ specification for details on what the robot should do to resolve each kind of
+ error
+- [ ] forward error codes to the pc-communication module
+
+empty function declarations are in place for providing other modules an error
+reporting function.
+
+### i/o read & write
+
+the i/o module reads all inputs once and writes all outputs once. this keeps
+cycle time constant, and makes sure no time is wasted re-reading inputs, or
+writing outputs more than once.
+
+- [ ] create `struct`s for each type of input:
+ - [ ] button
+ - [ ] infrared light sensor
+ - [ ] time-of-flight distance sensor
+- [ ] create a single `struct` that holds all input data
+- [ ] create a single `struct` that holds output data values for:
+ - [ ] left motor speed
+ - [ ] right motor speed
+ - [ ] red led
+ - [ ] green led
+
+extra (requires external interrupt setup):
+- [ ] add a `pressed` property to the button struct that turns on if the button
+ was pressed outside the i/o module execution span
+- [ ] add a `press_duration` property to the button struct that measures button
+ press duration, and that works when the button is pressed outside the i/o
+ module execution span
+
+technically the wixel serial channel, programmer debug serial channel, lcd
+contents and speaker tones are also considered outputs, but these all take
+significant time or memory to update, so these will not be updated using the
+cyclic i/o module.
+
+### modes
+
+modes is a shim module that forwards execution to the currently selected mode.
+the global variable `g_w2_current_mode` holds a pointer to the current mode.
+this makes sure only a single mode handler gets ran on every execution cycle.
+
+### maze
+
+the maze mode controls the robot when it's in the maze, and sets execution to
+grid mode when it detects the maze-grid transition. the solving algorithm will
+constantly keep either left or right until (a) the maze-grid transition is
+detected, (b) the charging pad is detected, or (c) the starting point is
+detected. depending on which location is desired, the robot may continue to
+venture through the maze when it finds any of these. exact implementation
+details for this mode are yet to be determined.
+
+### warehouse
+
+the warehouse mode controls the robot when it's in the warehouse, and sets
+execution to maze mode when it detects the maze-grid transition. exact
+implementation details for this mode are yet to be determined.
+
+### emergency stop
+
+> this mode can't be implemented until the pc-communication protocol spec is
+> finished
+
+the emergency stop mode stops the robot from doing anything until the user
+determines it is safe to resume execution.
+
+- [ ] create a global variable that holds the previous mode
+- [ ] create a global variable that holds a 'safe' state (startup/default
+ value = false)
+- [ ] add a condition in the supervisor that switches to the emergency mode if
+ the 'safe' state variable is false
+- [ ] add a condition in the emergency mode handler that switches to the
+ previous mode if the 'safe' state returns to false
+
+### calibration
+
+the calibration sequence is used during the maze mode for re-finding the line
+when the robot gets lost. the robot will first try to find the line by itself
+when it gets lost. when it does this it will send a warning to the error
+buffer. in case it can't find the line anymore, it will go into emergency mode
+and send a critical warning.
+
+- [ ] implement line-finding sequence
+ - turn 360 degrees (about robot's own axis)
+ - if a line is found at any point during this rotation, stop turning
+ - if a full rotation is completed without a found line, enter emergency
+ mode
+- [ ] add a warning for line lost