commit 4668458f2f77350fe0dd79e66651ddbb55b972b5
from: Thomas Böhler <witcher@wiredspace.de>
date: Thu Mar 30 08:19:25 2023 UTC

improving: explain esp32 code listings

commit - 07fd431c751bbf532f53c9eb70751f079f9cbe6f
commit + 4668458f2f77350fe0dd79e66651ddbb55b972b5
blob - 7c876d4fd02f04c63b273b1d59c6b9b6b447083a
blob + 10947267d28e80a2f1c809e534bc5b399003e038
--- src/chapters/improving_throughput/setup.tex
+++ src/chapters/improving_throughput/setup.tex
@@ -65,10 +65,11 @@ A high-level overview of the connection and data excha
 	\label{fig:high_level_sequence_diagram_connection_used}
 \end{figure}
 
-The setup for the server is done in the \lstinline{setup} method of the
-\href{https://git.sr.ht/~witcher/esp32-ble-throughput}{esp32-ble-throughput}
-repository. The setup of the \lstinline{buffer_len} characteristic is shown in
-Listing \ref{lst:buffer_len_char_setup}.
+The setup for the server is done in the \lstinline{setup} method of
+\href{https://git.sr.ht/~witcher/esp32-ble-throughput}{esp32-ble-throughput}.
+The setup of the \lstinline{buffer_len} characteristic is shown in Listing
+\ref{lst:buffer_len_char_setup}, along with the function signature of the
+\lstinline{Characteristic::new} method.
 
 \begin{lstfloat}
 	\begin{lstlisting}[
@@ -77,6 +78,15 @@ Listing \ref{lst:buffer_len_char_setup}.
 				server.},
 		label={lst:buffer_len_char_setup}
 	]
+    // pub fn new(
+    //     uuid: UUID,
+    //     perms: Permissions,
+    //     max_length: u16,
+    //     initial_value: Option<Vec<u8>>,
+    //     descriptors: Vec<Descriptor>,
+    //     on_change_callback: Option<fn(Vec<u8>)>,
+    // ) -> Characteristic
+
     let mut buf_len = Characteristic::new(
         BUFFER_LEN_UUID.into(),
         Permissions::ReadWrite,
@@ -89,6 +99,14 @@ Listing \ref{lst:buffer_len_char_setup}.
 	\end{lstlisting}
 \end{lstfloat}
 
+The \lstinline{new} method on the \lstinline{Characteristic} struct creates a
+new characteristic with a given \ac{uuid}, permissions, maximum length of the
+data inside, the initial value of the characteristic, descriptors (which are
+unused), and a callback that will be called when this characteristic changed.\\
+The size of the characteristic will be the same that is used to store a
+\lstinline{usize} in memory. The initial value is the length of the buffer as
+specified later in Table \ref{table:parameters_none}.
+
 In order to calculate the throughput the server registers a callback for the
 \lstinline{data_buffer} characteristic, seen in Listing
 \ref{lst:buffer_data_char_setup}, that is called whenever the characteristic is
@@ -114,6 +132,14 @@ written to, with the callback defined in Listing
 	\end{lstlisting}
 \end{lstfloat}
 
+In a similar way to Listing \ref{lst:buffer_len_char_setup}, Listing
+\ref{lst:buffer_data_char_setup} uses the \lstinline{Characteristic::new} method
+to create a new characteristic with the appropriate values for it. The most
+notable change is the value of the \lstinline{initial_value} descriptor as it is
+0 but initialized through an iterator, as usually seen in functional
+programming. This is needed since the method requires a \lstinline{Vec} to be
+given.
+
 \begin{lstfloat}
 	\begin{lstlisting}[
 		gobble=4,
@@ -133,7 +159,14 @@ written to, with the callback defined in Listing
 
 The \lstinline{handle_buffer_write} callback is only 2 lines long as it is a
 wrapper around the \lstinline{recv} method on the \lstinline{ThroughputState},
-which is defined as a global variable guarded by a mutex.
+which is defined as a global variable guarded by a mutex. The \lstinline{recv}
+method keeps track of the bytes and sequence number received.\\
+Allowing the Clippy lint \lstinline{needless_pass_by_value} is required because
+Clippy sees that the parameter is owned by the function even though it doesn't
+need to be; nowhere is the ownership needed as the value is only read, so a
+non-owned type is suggested instead. This lint cannot be satisfied as the
+signature for the callback method is \textit{required} to be the one shown, so
+the lint is deactivated.
 
 \lstinline{ThroughputState} keeps track of the state and is a struct defined in
 Listing \ref{lst:throughput_state_definition}. It keeps track of the time passed
@@ -269,8 +302,8 @@ base throughput needs to be established. The throughpu
 above was measured with {\textasciitilde}4 \ac{kbps}. The parameters set for
 this test can be seen in Table \ref{table:parameters_none}. The parameters are
 the \ac{le} \ac{phy}, \ac{dle}, \ac{att} operation, and the \ac{att} \ac{mtu}
-used. These will be explained in Sections \ref{sec:phy}, \ref{sec:dle},
-\ref{sec:write_command}, and \ref{sec:att_mtu} respectively.
+used. These parameters will be explained in Sections \ref{sec:phy},
+\ref{sec:dle}, \ref{sec:write_command}, and \ref{sec:att_mtu} respectively.
 
 \begin{table}[ht]
 	\centering