diff options
author | Nao Pross <naopross@thearcway.org> | 2018-02-02 12:12:18 +0100 |
---|---|---|
committer | Nao Pross <naopross@thearcway.org> | 2018-02-02 12:12:18 +0100 |
commit | 18abece8f8a8af17a3b5e80dc1baf61457409600 (patch) | |
tree | 66f64fb9ea91d8a26c56af95c66e5bb7b8f8b5c3 /doc | |
parent | Move to version control (diff) | |
download | Xilofono-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 'doc')
-rw-r--r-- | doc/data/misure-xilofono-note.txt | 11 | ||||
-rw-r--r-- | doc/data/misure-xilofono.csv | 30 | ||||
-rw-r--r-- | doc/lista_componenti.ods | bin | 16250 -> 20711 bytes | |||
-rw-r--r-- | doc/xilofono.tex | 240 |
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 Binary files differindex 4ecfd6f..27c34b5 100644 --- a/doc/lista_componenti.ods +++ b/doc/lista_componenti.ods 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 |