summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorNao Pross <naopross@thearcway.org>2018-02-02 12:12:18 +0100
committerNao Pross <naopross@thearcway.org>2018-02-02 12:12:18 +0100
commit18abece8f8a8af17a3b5e80dc1baf61457409600 (patch)
tree66f64fb9ea91d8a26c56af95c66e5bb7b8f8b5c3 /doc
parentMove to version control (diff)
downloadXilofono-18abece8f8a8af17a3b5e80dc1baf61457409600.tar.gz
Xilofono-18abece8f8a8af17a3b5e80dc1baf61457409600.zip
2 February 2018
Documentation: - new API documentation - datasheets for new components - update BOM - update documentation data Hardware: - update schematic for MIDI connector Software: - new MIDI API - update prject target to PIC18F45K22
Diffstat (limited to '')
-rw-r--r--doc/data/misure-xilofono-note.txt11
-rw-r--r--doc/data/misure-xilofono.csv30
-rw-r--r--doc/lista_componenti.odsbin16250 -> 20711 bytes
-rw-r--r--doc/xilofono.tex240
4 files changed, 273 insertions, 8 deletions
diff --git a/doc/data/misure-xilofono-note.txt b/doc/data/misure-xilofono-note.txt
new file mode 100644
index 0000000..b7f277c
--- /dev/null
+++ b/doc/data/misure-xilofono-note.txt
@@ -0,0 +1,11 @@
+Tutte le misure sono prese in millimetri (mm).
+
+Ogni foro e' largo 6mm alto 5mm.
+
+Con foro basso di un listello si intende il foro piu' vicino a se' quando si
+tiene lo xilofono per suonare.
+
+Le coordinate XY di ogni foro sono prese nell'angolo* in basso a sinistra,
+rispetto all'angolo* in basso a sinistra del foro basso della prima nota C2.
+
+* il foro e' quadrato \ No newline at end of file
diff --git a/doc/data/misure-xilofono.csv b/doc/data/misure-xilofono.csv
new file mode 100644
index 0000000..8e04159
--- /dev/null
+++ b/doc/data/misure-xilofono.csv
@@ -0,0 +1,30 @@
+Nota;Altezza;Larghezza;X Foro;Y Foro Basso;Y Foro Alto;
+c2;220;25;0;0;123;
+d2;209;25;30;9;126;
+e2;196;25;60;18;128;
+f2;191;25;90;22;130;
+g2;181;25;120;30;132;
+a2;171;25;150;38;134;
+b2;161;25;180;45;136;
+c3;156;25;210;49;138;
+d3;148;25;240;56;140;
+e3;139;25;270;61;142;
+f3;135;25;300;65;144;
+g3;127;25;330;70;146;
+a3;120;25;360;80;148;
+b3;113;25;390;83;150;
+c4;110;25;420;87;152;
+;;;;;;
+c#2;;;;;;
+d#2;;;;;;
+;;;;;;
+F#2;;;;;;
+g#2;;;;;;
+a#2;;;;;;
+;;;;;;
+c#3;;;;;;
+d#3;;;;;;
+;;;;;;
+f#3;;;;;;
+g#3;;;;;;
+a#3;;;;;;
diff --git a/doc/lista_componenti.ods b/doc/lista_componenti.ods
index 4ecfd6f..27c34b5 100644
--- a/doc/lista_componenti.ods
+++ b/doc/lista_componenti.ods
Binary files differ
diff --git a/doc/xilofono.tex b/doc/xilofono.tex
index a2b473e..0ad9ddc 100644
--- a/doc/xilofono.tex
+++ b/doc/xilofono.tex
@@ -2,17 +2,34 @@
% language / document
\usepackage[italian]{babel}
+
+% font
\usepackage{lmodern} % font
\usepackage{anyfontsize}
+
+% urls
+\usepackage{url}
+\urlstyle{tt}
+
% figures
\usepackage{float} % place figures
\usepackage{pgfplots} % plts
+\usepackage{tikz-timing}
\usepackage[european]{circuitikz} % circuiti elettrici
\usepackage{tikzscale} % scale tikz images
+\pgfplotsset{compat=1.15}
+% tables
+\usepackage{array}
+\usepackage{booktabs}
-\pgfplotsset{compat=1.15}
+% code
+\usepackage{listings}
+% parskip
+\setlength{\parskip}{1em}
+
+% metadata
\title{Xilofono MIDI}
\author{Naoki Pross, \textit{SAM Bellinzona}}
@@ -25,10 +42,10 @@
\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.
-Esso \`e costruito utilizzando parti da uno Xilofono ``Sonor Tag 25'' modificato con dell'elettronica esterna.
+Esso \`e costruito utilizzando parti da uno Xilofono ``Sonor Tag 25'' modificato con dei circuiti di misura.
\section{Elemento piezoelettrico}
-Il sensore piezoelettrico quando colpito genera una tensione oscillante come mostrato nella figura \ref{fig:piezo-waveform}. La tensione generata dal piezo \`e pi\`u che sufficiente per entrare direttamente in un circuito digitale di misura CMOS; l'unica correzione necessaria \`e la parte negativa dell'oscillazione che deve essere smorzata.
+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}[
@@ -38,14 +55,12 @@ Il sensore piezoelettrico quando colpito genera una tensione oscillante come mos
grid=major,
grid style=dotted
]
-
\addplot [color=black, smooth, thick] table [
mark=none,
each nth point=2,
x=Time, y=Smooth,
col sep=semicolon
] {data/piezo-waveform.csv};
-
\end{axis}
\end{tikzpicture}
\caption{
@@ -55,16 +70,225 @@ 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 da un elemento piezoelettrico, che rileva il colpo, ed un comparatore per digitalizzare il segnale per il microcontroller.
+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=\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.
-\section{Software}
-\subsection{Formato MIDI}
+\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}.
+
+\subsection{Specifiche hardware}
+Il protocollo MIDI \`e composto da pi\`u parti per il trasporto, i file e per l'hardware. Per questo progetto \`e utilizzato unicamente il protocollo di trasporto, le informazioni sono trasmesse attraverso una porta seriale RS232 a due fili, utilizzando il connettore di uscita DIN 5 Pin (DIN 41524).
+
+\begin{figure}[H]
+\centering
+\begin{tikzpicture}[scale=1.5]
+ \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}
+
+Il formato originale per la trasmissione seriale MIDI \`e un \emph{current loop} a cui il valore logico 0 \`e assegnato al passaggio di una corrente di 5 mA\cite{gweep}.
+
+\subsection{Specifiche software}
+La trasmissione seriale MIDI \`e definita come standard a \(31'250\pm 1\%\) baud con 1 start bit, frame da 8 bit e 1 stop bit. Un messaggio (o pacchetto)\footnote{In questo documento i due termini sono utilizzati intercambiabilmente.} MIDI incomincia con uno \emph{Status Byte} (vedi tabella \ref{tab:status-bytes}) seguito se necessario da altri byte di dati.
+Per migliorare le prestazioni \`e definito che se il byte di status viene omesso, il dispositivo ricevente assume che lo status sia uguale all'ultimo messaggio ricevuto (running status).
+
+\subsection{Protocollo -- Messaggi di canale}
+Il nibble (4 bit) basso del byte di status viene utilizzato per la selezione del canale. I 16 canali disponibili sono controllati mandando dei pacchetti di tipo \emph{channel voice} o di tipo \emph{channel mode}.
+
+\subsubsection{Channel mode}
+Un messaggio con status \texttt{0xBn} se il primo dato \(D_0 \geq 120\) \`e detto un pacchetto \emph{channel mode}. Il pacchetto viene interpretato come un impostazione del \emph{base channel}, ossia modifica le impostazioni dell'intero canale.
+\begin{figure}[H]
+\centering
+\begin{tikzpicture}[scale=2]
+ \timing at (0, 0) {L5D{1000 nnnn}5D{0111 1011}5D{ 0000 0000 }L};
+\end{tikzpicture}
+\caption{Esempio di messaggio channel mode ANO (all notes off) che ha \(D_0 = 123\) (\(\geq 120\))}
+\end{figure}
+
+\subsubsection{Channel voice}
+I messaggi con status tra \texttt{0x8n} e \texttt{0xEn}, esclusi i pacchetti channel voice, sono detti pacchetti \emph{channel voice} e servono per indicare al dispositivo come deve suonare una nota (controllo della voce).
+\begin{figure}[H]
+\centering
+\begin{tikzpicture}[scale=2]
+ \timing at (0, 0) {L5D{1000 nnnn}5D{ 0111 0xxx }L};
+\end{tikzpicture}
+\end{figure}
+
+\subsection{Protocollo -- Messaggi di sistema}
+I messaggi di sistema generalmente sono utilizzati per impostare la configurazione del dispositivo ricevente e non sono quindi utilizzati per riprodurre suoni o note.
+I messaggi di sistema sono a loro volta suddivisi in 3 tipi.
+
+\subsubsection{System Exclusive}
+\subsubsection{System Common}
+\subsubsection{System Real Time}
+
+\subsection{Messaggi di interesse per il progetto}
+
+\section{Implementazione dell'API MIDI}
+\subsection{API multipiattaforma}
+Per il progetto \`e stato implementato un API (Application Programming Interface) che permette di generare in maniera conveniente dei messaggi MIDI.
+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}
+typedef struct {
+ unsigned status :4;
+ unsigned channel :4;
+ uint8_t data[];
+} midi_message_t;
+\end{verbatim}
+\end{minipage}
+
+Sono definite in oltre le seguenti enumerazioni per migliorare la leggibilit\`a del codice.
+
+\begin{minipage}{\linewidth}
+\begin{verbatim}
+typedef enum {
+ C = 0, // Do
+ D = 1, // Re
+ E = 2, // Mi
+ F = 3, // Fa
+ G = 4, // Sol
+ A = 5, // La
+ B = 6, // Si
+} midi_note_t;
+\end{verbatim}
+\end{minipage}
+
+\begin{minipage}{\linewidth}
+\begin{verbatim}
+typedef enum {
+ NOTE_ON = 0x8,
+ NOTE_OFF = 0x9,
+ POLYPHONIC_KEYPRESS = 0xA,
+ CONTROLLER = 0xB,
+ PROGRAM_CHANGE = 0xC,
+ CHANNEL_PRESSURE = 0xD,
+ PITCH_BLEND = 0xF
+} midi_status_t;
+\end{verbatim}
+\end{minipage}
+
+\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 instanziare 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}
+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}
+
+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}
+typedef struct {
+ unsigned status :4;
+ unsigned channel :4;
+
+#ifdef MIDI_DYNAMIC_MEMORY_ALLOC
+ uint8_t data[];
+#else
+ size_t data_size;
+ uint8_t data[MIDI_DATA_MAX_SIZE];
+#endif
+} midi_message_t;
+\end{verbatim}
+\end{minipage}
+
+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.
+
+\begin{minipage}{\linewidth}
+\begin{verbatim}
+int eusart_write_midi(midi_message_t *pkt)
+{
+ if (pkt == NULL) {
+ return -1;
+ }
+
+ if (pkt->data == NULL) {
+ return -2;
+ }
+
+ size_t length = pkt->data_size;
+ uint8_t *data = pkt->data;
+
+ putch((pkt->status<<4) | pkt->channel);
+
+ while (length--) {
+ putch(*(data++));
+ }
+
+ return 0;
+}
+\end{verbatim}
+\end{minipage}
+
+
+\begin{table*}[ht]
+\caption{Sommario degli status bytes\label{tab:status-bytes}}
+\centering
+\begin{tabular}{>{\tt}c >{\tt}c c l}
+ \toprule
+ \multicolumn{2}{c}{\bfseries Status Byte} & \bfseries Data size & \bfseries Descrizione \\
+ \footnotesize Hex & \footnotesize Bin & & \\
+ \midrule
+ 8n & 1000 nnnn & 2 & Note off \\
+ 9n & 1001 nnnn & 2 & Note on \\
+ An & 1010 nnnn & 2 & Polyphonic key (Aftertouch) \\
+ Bn & 1011 nnnn & 2 & Controller \( D_0 < 120 \) \\
+ Cn & 1100 nnnn & 1 & Program change \\
+ Dn & 1101 nnnn & 1 & Channel pressure (Aftertouch) \\
+ En & 1110 nnnn & 2 & pitch bend \\
+ \midrule
+ Bn & 1011 nnnn & 2 & Select channel mode \(D_0 \geq 120 \) \\
+ \midrule
+ F0 & 1111 0000 & variable & System exclusive \\
+ Fx & 1111 0xxx & 0 to 2 & System common \\
+ Fx & 1111 1xxx & 0 & System real time \\
+ \bottomrule
+\end{tabular}
+\end{table*}
+
+\begin{thebibliography}{9}
+\bibitem{wiki:midi}
+ \textit{Musical Instrument Digital Interface},
+ [online], (visitato il 18.01.2018) \\
+ \url{https://it.wikipedia.org/w/index.php?title=Musical_Instrument_Digital_Interface}
+
+\bibitem{somascape}
+ \textit{Guide to the MIDI Software Specification},
+ [online], (visitato il 18.01.2018) \\
+ \url{http://www.somascape.org/midi/tech/spec.html}
+
+\bibitem{gweep}
+ \textit{The MIDI Specification},
+ [online], (visistato il 22.01.2018) \\
+ \url{http://www.gweep.net/~prefect/eng/reference/protocol/midispec.html}
+\bibitem{xc8}
+ \textit{MPLAB® XC8 C Compiler User’s Guide},
+ 2012 Microchip Technology Inc,
+ ISBN: 978-1-62076-375-9,
+ http://ww1.microchip.com/downloads/en/DeviceDoc/52053B.pdf
+\end{thebibliography}
\end{document} \ No newline at end of file