From 2e87afcdd54d4592dcc937cea9ec3f283ee6726c Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 1 Jun 2024 14:28:58 +0200 Subject: WIP puzbusv2??? --- .editorconfig | 2 +- docs/.gitignore | 1 + docs/design.adoc | 73 ++++++++++++++++++--------------- docs/figs.drawio | 26 ++++++------ docs/img/busmaster-sequence.puml | 22 ++++++++++ docs/img/busmaster-sequence.svg | 1 + docs/img/puzzle-module-common-state.svg | 2 +- docs/img/theme.ipuml | 6 +++ docs/makefile | 5 +++ 9 files changed, 90 insertions(+), 48 deletions(-) create mode 100644 docs/img/busmaster-sequence.puml create mode 100644 docs/img/busmaster-sequence.svg create mode 100644 docs/img/theme.ipuml diff --git a/.editorconfig b/.editorconfig index cd37156..4de909a 100644 --- a/.editorconfig +++ b/.editorconfig @@ -5,7 +5,7 @@ indent_style = tab end_of_line = lf insert_final_newline = true -[*.md] +[*.{md,adoc}] indent_style = space indent_size = 2 diff --git a/docs/.gitignore b/docs/.gitignore index a2f45c2..1b1c365 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,5 +1,6 @@ *.pdf res +*.bkp # i know this is bad Gemfile.lock diff --git a/docs/design.adoc b/docs/design.adoc index 5ebbb15..e35c495 100644 --- a/docs/design.adoc +++ b/docs/design.adoc @@ -203,7 +203,7 @@ image::img/system-bus.svg[] == Modules This section elaborates on the top-level specifications from <> with -additional hardware specifications and software design decisions. +software design decisions and protocol specifications. === Puzzle Module Framework @@ -222,38 +222,6 @@ designed to facilitate the following: * Provide abstracted interfaces to allow for easy integration of the puzzle box as part of a larger whole (<>). -[[sec:framework-state]] -==== State - -All puzzle modules implement the same state machine shown in -<>. Note that the arrows indicate state -transitions that a puzzle module may take on its own. The main controller also -allows the game operator to manually set the current state as one of the states -on the right half of <>, which can be used to -skip a puzzle if a player is stuck (<>) or -reset a game if it is malfunctioning (<>). - -Puzzle modules start in the 'uninitialized' state, where they repeatedly send -messages to the main controller (see <>). The state transition -from 'uninitialized' to 'reset' is forced by the main controller upon -initialization. States on the right half of <> -are used during gameplay. - -[[fig:puzzle-module-common-state]] -.Global puzzle module state machine -image::img/puzzle-module-common-state.svg[] - -The state machine described in <> is referred -to as the global state. Puzzle modules may also declare and define custom state -variables, which is referred to as auxiliary state. These auxiliary state -variables contain game-specific variables; e.g. the binary state of each button -on the Neotrellis puzzle module, or the last passcode entered on the vault -puzzle module. - -Separating the auxiliary state from the generic state allows the main -controller to handle the auxiliary state as an arbitrary blob, which allows for -future expansion without modification of the main controller software. - ==== Commands The puzzle module framework describes the following commands: @@ -277,6 +245,45 @@ this, the 'update' command was created. This command is utilized for various kinds of updates, including registering new puzzle modules and updating global state. + +[[sec:framework-state]] +==== State + +All puzzle modules implement the same state machine shown in +<>. Note that the arrows indicate state +transitions that a puzzle module may take on its own. The main controller also +allows the game operator to manually set the current state as one of the states +on the right half of <>, which can be used to +skip a puzzle if a player is stuck (<>) or +reset a game if it is malfunctioning (<>). + +- Puzzle modules start in the 'uninitialized' state, during which they wait for + a handshake command (magic) from the main controller. Once the magic reply is + sent, the puzzle module transitions to the _idle_ state. +- During the 'idle' state, the puzzle module waits until the main controller + forces it into the _playing_ state. +- While in the 'playing' state, the puzzle module is active, and may be solved + by the player(s). The puzzle module's game logic is responsible for checking + if the game is finished, upon which it will transition to the _solved_ state. +- The 'solved' state is similar to the 'idle' state, with the exception that + the main controller will not re-start this puzzle module. Unless a module is + manually reset by the game operator, it does not return from this state. + +[[fig:puzzle-module-common-state]] +.Global puzzle module state machine +image::img/puzzle-module-common-state.svg[] + +The state machine described in <> is referred +to as the _global state_ of a puzzle module. Puzzle modules may also declare +and define custom state variables, which is referred to as _auxiliary state_. +These auxiliary state variables contain game-specific variables (e.g. the +binary state of each button on the Neotrellis puzzle module, or the last +passcode entered on the vault puzzle module). + +Separating the auxiliary state from the generic state allows the main +controller to handle the auxiliary state as an arbitrary blob, which allows for +future expansion without modification of the main controller software. + === Main Controller This subsection defines the function and state of the main controller. diff --git a/docs/figs.drawio b/docs/figs.drawio index a40503b..a43862d 100644 --- a/docs/figs.drawio +++ b/docs/figs.drawio @@ -1,4 +1,4 @@ - + @@ -437,27 +437,27 @@ - + - - - - + - - + + + + + - + - - + + - - + + diff --git a/docs/img/busmaster-sequence.puml b/docs/img/busmaster-sequence.puml new file mode 100644 index 0000000..362227a --- /dev/null +++ b/docs/img/busmaster-sequence.puml @@ -0,0 +1,22 @@ +@startuml +!include theme.ipuml + +participant "Main controller\n(0x00)" as main +participant "Vault PM\n(0x08)" as a +participant "NeoTrellis PM\n(0x09)" as b +participant "NeoTrellis unit 1\n(0x2e)" as neo1 +participant "NeoTrellis unit 2\n(0x2f)" as neo2 + +activate main +main -> a --++: SEX? +a -> main --++: SEX +||| +main -> b --++: SEX? +b -> neo1: I2C write +neo1 -> b: I2C read +b -> neo2: I2C write +neo2 -> b: I2C read +b -> main --++: SEX +||| + +@enduml diff --git a/docs/img/busmaster-sequence.svg b/docs/img/busmaster-sequence.svg new file mode 100644 index 0000000..22d9161 --- /dev/null +++ b/docs/img/busmaster-sequence.svg @@ -0,0 +1 @@ +Main controller(0x00)Vault PM(0x08)NeoTrellis PM(0x09)NeoTrellis unit 1(0x2e)NeoTrellis unit 2(0x2f)SEX?SEXSEX?I2C writeI2C readI2C writeI2C readSEX \ No newline at end of file diff --git a/docs/img/puzzle-module-common-state.svg b/docs/img/puzzle-module-common-state.svg index b5688ef..a3ac4bb 100644 --- a/docs/img/puzzle-module-common-state.svg +++ b/docs/img/puzzle-module-common-state.svg @@ -1,3 +1,3 @@ -
Uninitialized
Reset
Playing
Solved
 \ No newline at end of file +
uninitialized
uninitialized
idle
idle
playing
playing
solved
solved \ No newline at end of file diff --git a/docs/img/theme.ipuml b/docs/img/theme.ipuml new file mode 100644 index 0000000..23e0ce5 --- /dev/null +++ b/docs/img/theme.ipuml @@ -0,0 +1,6 @@ +!theme plain +skinparam DefaultFontSize 14 +skinparam DefaultFontName Inter +skinparam RoundCorner 0 +skinparam maxMessageSize 200 +hide footbox diff --git a/docs/makefile b/docs/makefile index f175830..370d2db 100644 --- a/docs/makefile +++ b/docs/makefile @@ -19,3 +19,8 @@ ASCIIDOCTOR_ARGS += --backend pdf %.pdf: %.adoc $(PDFDEPS) bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $< +%.svg: %.puml img/theme.ipuml + plantuml -tsvg $< + + + -- cgit v1.2.3