From dd152f500f510bb59d261936466d5143f9592b05 Mon Sep 17 00:00:00 2001
From: Nao Pross <naopross@thearcway.org>
Date: Fri, 2 Mar 2018 10:01:32 +0100
Subject: Add automatic configuration and hardware bugfix (via sw)

---
 doc/xilofono.tex | 150 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 114 insertions(+), 36 deletions(-)

(limited to 'doc/xilofono.tex')

diff --git a/doc/xilofono.tex b/doc/xilofono.tex
index 6ada6aa..d8b06ed 100644
--- a/doc/xilofono.tex
+++ b/doc/xilofono.tex
@@ -1,8 +1,5 @@
 \documentclass[a4paper, 10pt]{report}
 
-% layout
-\usepackage[margin=3cm]{geometry}
-
 % language / document
 \usepackage[italian]{babel}
 
@@ -10,6 +7,7 @@
 \usepackage{lmodern} % font
 \usepackage{anyfontsize}
 
+
 % urls 
 \usepackage{url}
 \urlstyle{tt}
@@ -27,8 +25,31 @@
 \usepackage{booktabs}
 
 % code
+\usepackage{xcolor}
 \usepackage{listings}
 
+\lstdefinestyle{customc}{
+    belowcaptionskip=1\baselineskip,
+    breaklines=true,
+    frame=none,
+    % margin
+    xleftmargin=\parindent,
+    % numbers
+    numbers=left,
+    numbersep=5pt,
+    numberstyle=\footnotesize\color{gray},
+    %
+    language=C,
+    showstringspaces=false,
+    % font
+    basicstyle=\ttfamily\normalsize,
+    keywordstyle=\color{green!40!black},
+    commentstyle=\color{gray},
+    identifierstyle=\color{black},
+    stringstyle=\color{orange},
+}
+\lstset{escapechar=@,style=customc}
+
 % parskip
 \setlength{\parskip}{1em}
 
@@ -36,6 +57,14 @@
 \title{Xilofono MIDI}
 \author{Naoki Pross, \textit{SAM Bellinzona}}
 
+% layout
+\usepackage[margin=3cm]{geometry}
+\usepackage{titlesec}
+
+\titleformat{\chapter}[hang]{\Huge\bfseries}
+	{\thechapter.}{.8em}{\Huge}
+\titlespacing*{\chapter}{0pt}{-30pt}{10pt}
+
 
 \begin{document}
 \maketitle
@@ -43,17 +72,20 @@
 %\begin{abstract}
 %\end{abstract}
 
+% ---------------------------------------------------
 \chapter{Introduzione}
 \section{Requisiti}
-Lo Xilofono digitale \`e un dispositivo in grado di rilevare le note suonate dall'utente per poi salvarle in un dispositivo esterno in formato MIDI.
+Lo Xilofono MIDI \`e un dispositivo in grado di rilevare le note suonate dall'utente per poi salvarle in un dispositivo esterno in formato MIDI.
 Esso \`e costruito utilizzando parti da uno Xilofono ``Sonor Tag 25'' modificato con dei circuiti di misura.
 
+% ---------------------------------------------------
+\chapter{Hardware}
 \section{Elemento piezoelettrico}
 Il sensore piezoelettrico quando colpito genera una tensione oscillante come mostrato nella figura \ref{fig:piezo-waveform}. La tensione generata ha bisogno solamente di una correzzione minimale per poter entrare in un circuito di misura CMOS. \`E necessario quindi rimuovere o smorzare la parte negativa dell'oscillazione.
 \begin{figure}[H] \centering
 \begin{tikzpicture}
 \begin{axis}[
-	ylabel={Tensione $u_x(t)$ [V]},
+	ylabel={Tensione $u_x(t)$[V]},
 	xlabel={Tempo $t$ [s]},
 	xmin=-0.05, xmax=0.4,
 	grid=major,
@@ -74,16 +106,72 @@ Il sensore piezoelettrico quando colpito genera una tensione oscillante come mos
 \end{figure}
 
 \section{Circuito di misura}
-Per ogni listello della tastiera dello strumento \`e presente un circuito di misura composto dall'elemento piezoelettrico, per rilevare il colpo, e dei diodi che limitano la tensione tra \(V_{cc}\) (5V) e \(V_{ss}\)(0V).
-
+Per ogni listello della tastiera dello strumento \`e presente un circuito di misura composto dall'elemento piezoelettrico, per rilevare il colpo, e dei diodi che limitano la tensione tra \(V_{cc}\) (5V) e \(V_{ss}\) (0V).
 Il piezoelettrodo utilizzato \`e un Murata 7BB-20-06 con una frequenza di risonanza di \(6.3\pm 0.6~\mathrm{kHz}\).
 \begin{figure}[H] \centering
 	\includegraphics[width=.5\linewidth]{figures/reduced-circ.tikz}
 	\caption{Circuito di misura}
 \end{figure}
 
-\section{Microcontroller}
-Per gestire i segnali forniti dai circuiti di misura \`e presente un PIC18F44K22, che esporta le informazioni delle note suonate in formato MIDI via seriale.
+% ---------------------------------------------------
+\chapter{Software}
+\section{Misurazione del piezoelettrodo}
+Non volendo utilizzare dei circuiti analogici per filtrare il segnale la correzione della misura viene effettuata dal microcontroller. Con una frequenza di campionamento regolabile tra gli 1 e i 4 kHz (attualmente impostata al massimo, 4kHz) il programma utilizza un sistema di maschere e shift, operazioni idealmente poco costose in performance, per determinare se una misura \`e un rimbalzo di una nota precedente o una nuova nota.
+
+Il microcontroller tiene una cronologia di 32 campioni per ogni nota salvando le misurazioni nei bit di un \texttt{uint32\_t}. Per aggiungere una nuova misura dunque \`e sufficiente un left shift ed un bitwise OR.
+\begin{lstlisting}
+key_data = (key_data << 1) | PORTXbits.PX0;
+\end{lstlisting}
+Per controllare che una misura non sia un rimbalzo, al dato contenente la cronologia (\texttt{key\_data}) viene applicata una maschera che controlla se ci sono gi\`a stati dei campioni validi in precedenza. In altre parole la maschera nasconde i campioni recenti e controlla che non ci siano campioni pi\`u vecchi al valore logico 1. Il valore della maschera viene impostato sperimentalmente. 
+\begin{lstlisting}
+#define NOTE_MASK 0xFFFFF000
+int is_pressed = key_data && !(key_data & NOTE_MASK);
+\end{lstlisting}
+
+% TODO write stuff
+\begin{figure}[H] \centering
+\begin{tikzpicture}
+\begin{axis}[
+	ylabel={Tensione $u_x(t)$ [V]},
+	xlabel={Tempo $t$ [s]},
+	% xmin=-0.02, xmax=0.02,
+	grid=major,
+	grid style=dotted,
+    width=\linewidth,
+    height=6.5cm
+]
+	% source
+	\addplot [color=blue!70, smooth] table [
+		mark=none,
+		each nth point=2,
+		x=Time, y=Voltage,
+		col sep=semicolon
+	] {data/piezo-filter-2/piezo-filter-waveform-ch1.csv};
+    
+    % not filtered
+	\addplot [color=gray!70, smooth] table [
+		mark=none,
+		each nth point=2,
+		x=Time, y=Voltage,
+		col sep=semicolon
+	] {data/piezo-filter-2/piezo-filter-waveform-ch3.csv};
+    
+    % filtered
+	\addplot [color=black, smooth, thick] table [
+		mark=none,
+		each nth point=2,
+		x=Time, y=Voltage,
+		col sep=semicolon
+	] {data/piezo-filter-2/piezo-filter-waveform-ch2.csv};
+\end{axis}
+\end{tikzpicture}
+\caption{
+	Tensione sul piezoelettrodo, il segnale misurato e il segnale filtrato.
+	\label{fig:piezo-filter-waveform}
+}
+\end{figure}
+
+
 
 \section{Protocollo MIDI}
 L'acronimo MIDI (Musical Instrument Digital Interface) indica il protocollo standard per l'interazione degli strumenti musicali elettronici, anche tramite un computer\cite{wiki:midi}.
@@ -93,10 +181,9 @@ Il protocollo MIDI \`e composto da pi\`u parti per il trasporto, i file e per l'
 
 \begin{figure}[H]
 \centering
-\begin{tikzpicture}[scale=1.5]
+\begin{tikzpicture}[scale=2]
 	\timing at (0,1)  {L4D{Status}4D{D0}4D{D1}4D{D2}4D{...}};
 	\timing at (0,.5) {L4D{0x90}4D{0x3C}4D{0x7F}4L4L};
-	%\timing at (0,0)  {
 \end{tikzpicture}
 \caption{Esempio di trasmissione MIDI}
 \end{figure}
@@ -145,20 +232,17 @@ Per il progetto \`e stato implementato un API (Application Programming Interface
 La struttura dati \texttt{midi\_message\_t} \`e allineata con dei bit-fields\cite[P.150]{xc8} ed un flexible array member (\texttt{data[]}) in modo da poter essere mandata direttamente come \texttt{void*} (void pointer) attraverso la seriale.
 
 % replace with lstings?
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 typedef struct {
     unsigned status :4;
     unsigned channel :4;
     uint8_t data[];
 } midi_message_t;
-\end{verbatim}
-\end{minipage}
+\end{lstlisting}
 
 Sono definite in oltre le seguenti enumerazioni per migliorare la leggibilit\`a del codice.
 
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 typedef enum {
     C = 0, 		// Do
     D = 1, 		// Re
@@ -168,11 +252,9 @@ typedef enum {
     A = 5, 		// La
     B = 6, 		// Si
 } midi_note_t;
-\end{verbatim}
-\end{minipage}
+\end{lstlisting}
 
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 typedef enum {
     NOTE_ON             = 0x8,
     NOTE_OFF            = 0x9,
@@ -182,28 +264,24 @@ typedef enum {
     CHANNEL_PRESSURE    = 0xD,
     PITCH_BLEND         = 0xF
 } midi_status_t;
-\end{verbatim}
-\end{minipage}
+\end{lstlisting}
 
 \subsection{API per dispositivi senza allocazione di memoria dinamica}
 Purtroppo alcuni microcontrollori, tra cui il PIC18F45K22 non supportano l'allocazione di memoria dinamica necessaria per allocare il flexible array member della struttura \texttt{midi\_message\_t}. Dunque la libreria MIDI \`e stata modificata per utilizzare la struttura dati come segue.
 
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 typedef struct {
     unsigned status :4;
     unsigned channel :4;
     size_t data_size;
     uint8_t data[MIDI_DATA_MAX_SIZE];
 } midi_message_t;
-\end{verbatim}
-\end{minipage}
+\end{lstlisting}
 
 Nello specifico, nel file header si presenta nel seguente modo.
 La macro \texttt{MIDI\_DYNAMIC\_MEMORY\_ALLOC}, normalmente non definita, indica all'API che pu\`o usufruire dell'allocazione dinamica. Quindi che le funzioni \texttt{malloc} e \texttt{free} siano implementate.
 
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 typedef struct {
     unsigned status  :4;
     unsigned channel :4;
@@ -215,14 +293,12 @@ typedef struct {
     uint8_t data[MIDI_DATA_MAX_SIZE];
 #endif
 } midi_message_t;
-\end{verbatim}
-\end{minipage}
+\end{lstlisting}
 
 Lo svantaggio di questa interfaccia \`e che non rende possibile mandare direttamente i pacchetti MIDI come un qualsiasi buffer. \`E necessario infatti implementare una funzione specifica per ogni piattaforma.
 A seguire un esempio abbastanza generico per le piattaforme che implementano la funzione \texttt{putch}.
 
-\begin{minipage}{\linewidth}
-\begin{verbatim}
+\begin{lstlisting}
 int eusart_write_midi(midi_message_t *pkt)
 {
   size_t lenght;
@@ -243,10 +319,9 @@ int eusart_write_midi(midi_message_t *pkt)
     
   return 0;
 }
-\end{verbatim}
-\end{minipage}
-
+\end{lstlisting}
 
+\chapter*{Allegati}
 \begin{table*}[ht]
 \caption{Sommario degli status bytes\label{tab:status-bytes}}
 \centering
@@ -272,6 +347,9 @@ int eusart_write_midi(midi_message_t *pkt)
 \end{tabular}
 \end{table*}
 
+\listoffigures
+\listoftables
+
 \begin{thebibliography}{9}
 \bibitem{wiki:midi}
 	\textit{Musical Instrument Digital Interface},
-- 
cgit v1.2.1

