extended ymodem documentation

doc/shellmatta_ymodem.dox

@@ -11,13 +11,16 @@
     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
+    In order to transmit the start characters 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).
 
+    When the transmission is complete the shellmatta requires to be polled
+    #YMODEM_POLL_NUMBER times. This ensures a short wait time to flush all
+    unwanted bytes from the transmitter.
 
-    The shellmatta_ymodem_start() function will return and the command it was
+    The shellmatta_ymodem_init() 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.
@@ -28,13 +31,15 @@
     @section shellmatta_ymodem_sequence Basic sequence
 
     @startuml
-        Application -> Shellmatta: shellmatta_ymodem_start()
-        Shellmatta -> Host: send NCK to start transmission
+        Application -> Shellmatta: shellmatta_ymodem_init()
+        Shellmatta -> Host: send C 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
+            Shellmatta -> Host: send C to start transmission
         end
+        Application -> Shellmatta: shellmatta_processData(first packet)
+        Shellmatta -> Application: packetHeader(fileSize, FileName) callback
         loop until shellmatta transmission is complete
             Host -> Shellmatta: Data transmission
             Shellmatta -> Application: packetRcv() callback
@@ -46,4 +51,36 @@
     When the ymodem is canceled from the Host the data received afterwards will
     be processed as usual.
 
+    @warning    Ymodem cannot cooperate with optional transport layer.
+                When the transport layer is enabled but not mandatory it is
+                forced to stay in the mode it was when the ymodem transfer
+                starts.
+                When the transport layer was active it has to keep active.
+                If it is inactive it cannot be activated during the ymodem
+                transfer.
+
+
+    @section shellmatta_ymodem_internal_buffer Internal buffer
+
+    To save some memory you can use the shellmatta ymodem module using the
+    internal buffer which usually is used to cache normal input before
+    processing it.
+
+    Just set the recvBuffer to NULL in #shellmatta_ymodem_init calls.
+
+
+    @warning    Ensure that your shellmattas buffer is at least
+                #YMODEM_PACKET_SIZE_1K large to fit the ymodem packet.
+                This is checked during initialization.
+
+
+    @section shellmatta_ymodem_paused_mode Paused mode
+
+    When the application requires time to process the currently received packet
+    the application can call #shellmatta_ymodem_pause from the callbacks.
+
+    This will prevent the shellmatta from sending the ACK to the sender.
+
+    When the processing is done just call #shellmatta_ymodem_resume.
+
 */