added documentation page for ymodem

doc/shellmatta.dox

@@ -45,4 +45,6 @@
 
     @subpage shellmatta_transport_layer
 
+    @subpage shellmatta_ymodem
+
 */

doc/shellmatta_ymodem.dox

@@ -0,0 +1,49 @@
+/**
+
+    @page shellmatta_ymodem Shellmatta ymodem
+
+    To be able to pass binary files to the shellmatta there is a ymodem module
+    implemented.
+    The ymodem reception can be started from a shellmatta command and handles
+    the handshaking as well as the data transmission.
+
+    As the shellmatta does not use dynamic memory every packet is passed
+    directly to the application using a callback.
+    Only the currently received packet is stored in the shellmatta internally.
+
+    In order to transmit the start NCKs to the sender you need to poll the
+    shellmatta_processData() function cyclically even if no new data has been
+    received.
+    Do this in 0.1s - 1s periods (depending on the latency you are after).
+
+
+    The shellmatta_ymodem_start() function will return and the command it was
+    called from will not be executed again. The rest of the ymodem processing
+    will be handled by the shellmatta. The data will be passed using the
+    callbacks registered during the start.
+
+    To cancel the ymodem (e.g. timeout) just call shellmatta_ymodem_cancel()
+
+
+    @section shellmatta_ymodem_sequence Basic sequence
+
+    @startuml
+        Application -> Shellmatta: shellmatta_ymodem_start()
+        Shellmatta -> Host: send NCK to start transmission
+        Shellmatta -> Application: return
+        loop until ymodem transmission starts (or is canceled)
+            Application -> Shellmatta: shellmatta_processData(null)
+            Shellmatta -> Host: send NCK to start transmission
+        end
+        loop until shellmatta transmission is complete
+            Host -> Shellmatta: Data transmission
+            Shellmatta -> Application: packetRcv() callback
+        end
+        Shellmatta -> Application: transmissionComplete() callback
+    @enduml
+
+    While the ymodem is active no command can be executed.
+    When the ymodem is canceled from the Host the data received afterwards will
+    be processed as usual.
+
+*/