merge main into wip/mc

1 files changed, 178 insertions, 135 deletions

diff --git a/docs/handover.adoc b/docs/handover.adoc
index 7bc52b3..efeec00 100644
--- a/docs/handover.adoc
+++ b/docs/handover.adoc
@@ -1,13 +1,19 @@
 :document: Handover Report
 include::share/meta.adoc[]
 
-== A Note Before Reading
-The team of year 2023-2024 consisted of only software students, meaning no 
-hardware was developed in this year. We were tasked with simplifying the 
-software to the point where it would only have to be ported into the new hardware,
-which was designed in the year 2022-2023. The goal of this year is to create
-a software framework which can be used to implement new puzzles and to make the 
-development process of these puzzles easier. 
+== Introduction
+
+This is an (at times slightly informal) document that summarizes how the 23-24
+run of this project went. We found the previous handover documents to be
+unhelpful when determining the 'actual' state of the project in the first few
+weeks, and felt they did not address the pitfalls of this project.
+
+The team of year 2023-2024 consisted of only software students (see
+<<tab:proj-comp>>), meaning no hardware was developed in this year. The goal of
+this year is to create a software framework which can be used to implement new
+puzzles and to make the development process of these puzzles easier, and allow
+the entire software stack to be ported to the the hardware designed by the
+22-23 group.
 
 Previous years' groups have put their predecessor's documents inside their own
 project folder, which has resulted in what we called the 'Russian doll folder
@@ -19,35 +25,21 @@ require credentials to log in. Please note that this is very much unofficial,
 and is not managed or endorsed by Avans. <<pn:blansch>> is the contact for
 removal or transfer of these files.
 
-== Introduction
-
-This is an informal document that summarizes how the 23-24 run of this project
-went. We found the previous handover documents to be unhelpful when determining
-the 'actual' state of the project in the first few weeks, and felt they did not
-address the pitfalls of this project.
+== Group history
 
-== Group History
-
-=== 19-20
-
-.19-20 group composition
-[%autowidth]
+[[tab:proj-comp]]
+.Project group composition
+[cols="15,35,20",width=55%]
 |===
-| Name | Study path
+| Year | Name | Study path
 
+.4+h| 19-20
 | Daniël Janssen | Software
 | Dion Legierse | Software
 | Jop van Laanen | Hardware
 | Max van den Heijkant | Software
-|===
-
-=== 20-21
-
-.20-21 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.4+h| 20-21
 | Joost van Wiechen | Hardware
 | Justin Maas | Software
 | [[pn:creemers,Merel Creemers]]Merel Creemers | Hardware{empty}footnote:[The
@@ -59,40 +51,19 @@ may indicate that they were removed from the project group. I am unsure if they
 were a hardware student that worked on the PCBs or a CMD student working on the
 puzzle box chassis.]
 | Vincent Lengowski | Hardware
-|===
-
-=== 21-22
-
-.21-22 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.5+h| 21-22
 | Alex van Kuijk | Hardware
 | Jef Baars | Software
 | Julian de Bruin | Software
 | Lucas van Gastel | Software
 | Toon Rockx | Hardware
-|===
-
-=== 22-23
-
-.22-23 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.2+h| 22-23
 | Frank Bekema | Hardware
 | Jasper Gense | Hardware
-|===
-
-=== 23-24 (current)
-
-.23-24 group composition
-[%autowidth]
-|===
-| Name | Study path
 
+.4+h| 23-24
 | Elwin Hammer | Software
 | [[pn:faase,Lars Faase]]Lars Faase{empty}footnote:[<<pn:faase>> was removed
 from the project group on 2024-06-03 following complaints about the lack of
@@ -101,98 +72,170 @@ communication, and lack of motivation] | Software
 | Thomas in 't Anker | Software
 |===
 
-== Project State
-The current project state is as follows: No new hardware has been designed 
-or developed this year. The software was completely revised, now consisting of a 
-a puzzle bus driver, a main controller, a simple CLI application, and two puzzle 
-modules. Namely the puzzle modules 'Vault' and 'Neotrellis', both using an Arduino 
-as the controller. The main controller (a RPI Pico W) can interact with the 
-different puzzle modules using an I^2^C bus. The I^2^C bus has been configured to 
-be a multi-master I^2^C bus, allowing the puzzle modules and the main controller 
-to initiate a I^2^C transmission. The main controller is able to find 
-new puzzle modules on startup, and does not check for new modules afterwards. A 
-simple CLI application has been developed, which can communicate with the main 
-controller through a TCP connection and simple commands. 
-
-In short: A puzzle bus driver has been implemented to allow for communication 
-between the main controller and the puzzle modules. A CLI application was developed 
-which connects with the main controller to monitor/edit the game state. And the 
-software for the puzzle modules 'Vault' and 'Neotrellis' is in the prototype state.
+== Project state
+
+The current project state is as follows:
+
+* No new hardware has been designed or developed this year
+* The software was completely revised, now consisting of
+** a puzzle bus driver (``pbdrv``)
+** a main controller
+** a simple CLI application
+** two puzzle modules ('Vault' and 'NeoTrellis') integrated using the puzzle
+	 bus driver
+
+Functionality:
+
+* The main controller (a RPI Pico W) can interact with the different puzzle
+	modules using a central shared I^2^C bus (referred to as the 'puzzle bus')
+* The main controller is able to find new puzzle modules on startup, and does
+	not check for new modules afterwards.
+* A simple CLI application has been developed, which can communicate with the
+	main controller through a TCP connection and allows control over various
+	aspects of the puzzle box using simple commands.
+
+Documentation:
+
+* These project documents
+* Detailed usage and API documentation for all software modules cite:[pbdox]
 
 == Incidents
-There were a multitude of different challenges we had to face before getting to a 
-working product. The majority of these have been documented here, and it is highly 
-recommended to have a look at this before development.
+
+During this year's run of the project, we encountered several difficuties we
+feel need to be addressed in order to be mitigated in future runs of the
+project. We recommend that these incidents are analyzed by future project
+groups and incorporated into the risk analysis section of future project plan
+documents.
+
+=== Documentation
+
+We spent too much time working on documentation at the start of the project.
+Make sure you set clear deadlines for documentation, and try not to spend too
+much time on review procedures, as these cost a lot of time.
+
+Our project documentation was originally written in Microsoft Word, but we
+later transferred all documentation to AsciiDoc because of issues where
+OneDrive would roll back changes. If possible, use a documentation system or
+format that allows using an external version control system like Git to avoid
+losing content. This is also the reason why our documents may contain
+formatting/style errors.
 
 === Misconceptions
-Make sure to know what you are developing and do some research beforehand, to make 
-sure you have the complete picture about what you are using. Sounds stupid, but it 
-happened for multiple project attempts, and caused time loss. This also includes 
-when you want to use documentation of previous years: go through the documentation 
-and verify it on the lowest possible level for the same reason as previously 
-mentioned.  
+
+Make sure to know what you are developing and do some research beforehand, to
+make sure you have a complete picture about what you are using. Sounds stupid,
+but it happened for multiple project attempts, and caused time loss. This also
+includes when you want to use documentation of previous years: go through the
+documentation and verify it on the lowest possible level for the same reason as
+previously mentioned.  
 
 === I^2^C
-I^2^C is easy to implement but also easy to underestimate, this project requires a 
-multi-master structure as communication is otherwise too complicated compared to 
-other means of communication.
-
-For I^2^C on hardware level: make sure to use pull-up resistors as it is otherwise 
-impossible to use I^2^C due to incorrect messages. This is also required for 
-controllers which are connected to the I^2^C bus. Make sure to use I^2^C devices 
-that support arbitration when using it as a multi-master. 
-
-The RPI Pico W (RP2040) does supports multi-master to the point of being able to 
-receive messages from other multi-masters as a slave while being configured as master. 
-Everything else about the I^2^C bus works, but due to this limitation a workaround has 
-been implemented to be able to continue using the RPI Pico W. 
-To simplify; a controller is needed which supports multi-master 
-while being able to be addressed as a slave.
-
-=== Available Hardware/SDKs
-When choosing or using specific chips/SDKs make sure it is available for (at least) 
-a few years. This makes it easier for the next project team to use the same chips/SDKs
-instead of having to find new ones. This also includes having enough development boards 
-for multiple people to program using the same setup, e.g. the RPI Pico W requires 
-another RPI Pico W to be debugged. Effectively requiring the project team to have at 
-least 4 RPI Pico Ws to be able to develop in the same environment (if there are 2 
-software students).
-
-=== Arduino
-Allocating memory using 'realloc' on Arduino is not possible, which makes it impossible 
-to use the 'mpack_writer_init_growable'.
-
-=== Garbage workarounds
-
-This section details unelegant workarounds that should be removed from the
-code. All workarounds are marked with ``FIXME:`` comments referring to one of
-the workarounds mentioned in this section.
-
-RP2040 I^2^C limitations::
-- All puzzle module drivers have a hard-coded 2 second delay between receiving
-	the MAGIC handshake request and the MAGIC handshake response handler. This
-	was done to ensure responses are not ignored by the RP2040 (main controller)
-	while it is still in I^2^C master mode.
+
+I^2^C is used because it is widely available and easy to implement. We strongly
+recommend 3rd year software students to refresh their knowledge on I^2^C before
+making major design decisions that rely on their conception of how to I^2^C bus
+works.
+
+Please note the following differences between I^2^C devices:
+
+- Regular I^2^C slave peripherals are allowed on the puzzle bus, and can be
+	connected to the puzzle bus as long as they do not cause issues with
+	addressing.
+- I^2^C master controllers must have hardware support for a multi-master
+	hardware configuration (i.e. support bus arbitration on a hardware level).
+	Arbitration support is required to prevent message corruption or electrical
+	shorts in a multi-master setup. Multi-master controllers may also be
+	connected to the puzzle bus, but only as long as they only interact with
+	regular I^2^C slave devices.
+- I^2^C multi-master controllers that are slave-addressable in master mode are
+	the only kind of I^2^C controller suitable for use in puzzle modules.
+	Microcontrollers with 2 I^2^C peripherals on the same bus (one in master
+	mode, one in slave mode) can also be used to achieve the same effect.
+
+The RP2040 supports multi-master, but is not addressable as a slave in master
+mode. This was mitigated using a workaround (see <<fixme:rp2040-i2c>>).
+
+=== Development hardware availability
+
+When choosing or using specific chips or development boards, make sure to
+include research on the product lifecycle. Choosing boards/chips that have
+planned long term support makes it easier for the next project team to order
+and use the same chips/boards instead of having to find new ones.
+
+Due to a lack of foresight, only 2 Picos were ordered this year, which caused
+unoptimal workload spread during the last weeks of the project. Because of
+this, we also strongly recommend making enough development boards available for
+multiple people to develop using the same setup. Note that the RPI Pico is a
+special case, as it requires another Pico for debugging, effectively requiring
+double the amount of hardware to support developers.
+
+Due to a misunderstanding, we also thought our development boards went missing
+somewhere during week 13. Double-checking if project materials were actually
+stolen, or making clear where the materials are stored by sending an image of
+its location could have easily avoided this from happening; make sure to do
+either.
+
+=== Auxiliary workarounds and technical limitations
+
+This section details workarounds that were implemented instead of being fixed
+due to time constraints or project scope. Workarounds that should be removed
+are marked with ``FIXME:`` comments referring to one of the workarounds
+mentioned in this section.
+
+[[fixme:rp2040-i2c,RP2040 I^2^C limitations]]
+<<fixme:rp2040-i2c>>::
+- The RP2040 is not slave-addressable while in master mode. A workaround that
+	uses both I^2^C peripherals simultaniously was written to work around this
+	issue.
+
+Memory management on Arduino::
+The Arduino's built-in memory management functions do not seem to work
+properly. The FreeRTOS heap 4 memory management functions are used on the
+puzzle modules instead. FreeRTOS does not have an implementation of the
+``realloc()`` function.
+- mpack's writer API cannot be used with a writer initialized using the
+	``mpack_writer_init_growable`` function on Arduino-based puzzle modules. The
+	``mpack_writer_init`` function is used with a static size buffer instead.
 
 == Recommendations
 
+This section details our recommendations on course of action for future project
+groups.
+
 === Imperatives
-* The 22-23 design document already mentions that the application of the I^2^C
-bus is in a multi-master configuration, but does not mention that this only
-works when pull-up resistors are used on the SCL and SDA lines. The pull-up
-resistors are required, as omitting them makes the bus arbitration process
-very inconsistent which causes frames to be dropped entirely.
-* Start creating prototypes as fast as possible; this benefits the project in the long run, 
-as you have already shown that certain parts of the project are already working and "only" 
-need to be integrated.
-* The Atmega328P chip is sufficient for the puzzle modules as it has enough I/O, mutli-master
-hardware support, and the ability to be addressed as a slave while being in master mode. 
-* The hardware design can be taken from the year 22-23, and the game rules are taken from 
-the year 20-21.
-
-// TODO: rename this bitch
-=== Loose imperatives 
-* The RPI Pico W has programmable IO modules, making it possible to create an I^2^C driver 
-that allows multi-master communication while still being addressable as a slave.
+
+The following points must not be dismissed by future project groups, as they
+are critical for project success:
+
+- The 22-23 design document already mentions that the application of the I^2^C
+	bus is in a multi-master configuration, but does not mention that this only
+	works when pull-up resistors are used on the SCL and SDA lines. The pull-up
+	resistors are required, as omitting them makes the bus arbitration process
+	very inconsistent which causes frames to be dropped entirely.
+- Start creating prototypes as early as possible; this benefits the project in
+	the long run, as you have already shown that certain parts of the project are
+	already working and "only" need to be integrated.
+- The Atmega328P and ATmega2560 MCUs are both sufficient for the puzzle modules
+	as they have enough I/O, mutli-master hardware support, and the ability to be
+	addressed as a slave while being in master mode.
+- The RPI Pico (and Pico W)'s I^2^C peripheral supports multi-master, but does
+	not support being addressed as a slave while in master mode. This is required
+	for puzzle bus integration, and was mitigated using a workaround (see
+	<<fixme:rp2040-i2c>>).
+
+=== Other suggestions
+
+These points are suggestions for future project groups. While we do not think
+these are critical to project success, we still think they are important to
+mention.
+
+- The hardware design from the year 22-23 should be implemented.
+- The original game rules are described in a separate document from the year
+	20-21.
+- The RPI Pico W has programmable I/O modules. Due to time constraints, we did
+	not research if these modules can be used to create a custom I^2^C peripheral
+	(and driver) that allows multi-master communication while still being
+	addressable as a slave. If this is possible, the RPI Pico W could be used
+	without the use of workarounds.
 
 include::share/footer.adoc[]