XModem Protocol

Implementation of the XMODEM Protocol compatible with .NET written in C#.

Supports XModem, XModem-1k & XModem-CRC.
This library can be used to send or receive bytes across a serial line.

Properties

Polynomial
Read/Write
int
Polynomial used by CRC lookup table. Defaulted to the polynomial X¹⁶ + X¹² + X⁵ + 1 (0x1021).
Data
Read/Write
System.Collections.Generic.IEnumerable<byte>
Data received from transfer or data to be sent.
Communicator
Write Only
XModemProtocol.Communication.ICommunicator
Accepts an instance of a class that implements the XModemProtocol.Communication.ICommunicator interface. Object will be used to facilitate the transfer of bytes.
Port
Write Only
System.IO.Ports.SerialPort
SerialPort to be used to create an instance of the XModemProtocol.Communication.Communicator class.
Options
Read/Write
XModemProtocol.Options.IXModemProtocolOptions
Accepts an instance of a class that implements the XModemProtocol.Options.IXModemProtocolOptions interface. This contains the bytes that XModemProtocol.XModemCommunicator will use to facilitate transfer along with some other options to customize how XModemProtocol.XModemCommunicator operates. By default, is instance of XModemProtocol.Options.XModemProtocolOptions.
State
Read Only
XModemProtocol.XModemStates
Returns the current state of XModemProtocol.XModemCommunicator.
Mode
Read/Write
XModemProtocol.XModemMode
Mode to be used by XModemProtocol.XModemCommunicator. If using Receive operation, CRC will upgrade to OneK automatically.

Methods

Send
public void Send()
Puts XModemProtocol.XModemCommuniator in the sender role awaiting initialization byte from receiver.
Receive
public void Receive()
Puts XModemProtocol.XModemCommunicator in the receiver role sending the initialization byte.
CancelOperation
public void CancelOperation()
Cancels operation currently running. No effect if no operation running.

Events supported

ModeUpdated
Fires when the mode of XModemProtocol.XModemCommunicator is updated.
StateUpdated
Fires when the state of XModemProtocol.XModemCommunicator is updated.
PacketsBuilt
Fires asynchronously whenever XModemProtocol.XModemCommunicator finishes building packets.
PacketToSend Fires when XModemProtocol.XModemCommunicator is ready to send a packet. A blocking method will prevent packet from being sent. Does not fire when sending IXModemProtocolOptions.EOT.
PacketReceived
Fires after a successful packet has been received by XModemProtocol.XModemCommunicator. This event must complete before XModemProtocol.XModemCommunicator will send IXModemProtocolOptions.ACK. Does not fire when IXModemProtocolOptions.EOT is received.
Aborted
Fires if the operation is aborted. XModemProtocol.XModemCommunicator will not return to being idle until event completes.
Completed
Fires when the operation completes successfully. XModemProtocol.XModemCommunicator will not return to being idle until event completes.
OperationPending
Fires before the operation begins, and determines whether operation will run or not. Will not fire if Data contains no bytes, and performing Send operation.

Configuration

XModemProtocol.XModemCommunicator.Mode, XModemProtocol.XModemCommunicator.Polynomial, and all members of XModemProtocol.Options.IXModemProtocolOptions may now be set in the configuration file.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="XModemProtocolConfiguration" type="XModemProtocol.Configuration.XModemProtocolConfigurationSection, XModemProtocol" />
  </configSections>
  <XModemProtocolConfiguration>
    <Polynomial value="4129"/>
    <Mode value="OneK"/>
    <CANSentDuringAbort value="5"/>
    <CancellationBytesRequired value="5"/>
    <SenderOneKPacketSize value="OneKOnly"/>
    <SenderInitializationTimeout value="10000"/>
    <SOH value="1"/>
    <STX value="2"/>
    <ACK value="6"/>
    <NAK value="21"/>
    <C value="67"/>
    <EOT value="4"/>
    <SUB value="26"/>
    <CAN value="24"/>
    <ReceiverConsecutiveNAKsRequiredForCancellation value="5"/>
    <ReceiverInitializationTimeout value="3000"/>
    <ReceiverTimeoutDuringPacketReception value="10000"/>
    <ReceiverMaxNumberOfInitializationBytesForCRC value="3"/>
    <ReceiverMaxNumberOfInitializationBytesInTotal value="10"/>
  </XModemProtocolConfiguration>
</configuration>

Simple Send Example

using XModemProtocol;
using System;
using System.IO.Ports;  
using System.IO;  

namespace XModemProtocolExample {

  class Program {

    static void Main(string[] args) {

      Console.WriteLine("XModemProtocol Send Example\n");
  
      // Set up Port.
      var port = new SerialPort{
        BaudRate = 230400,
        DataBits = 8,
        Parity = Parity.Even,
        StopBits = StopBits.One,
        PortName = "COM5",
      };
  
      // Instantiate XModemCommunicator.
      var xmodem = new XModemCommunicator();
  
      // Attach port.
      xmodem.Port = port;
  
      // Pass in Data.
      xmodem.Data = File.ReadAllBytes(@"C:\filetosend.hex");
  
      // Subscribe to events.
      xmodem.Completed += (s,e) => {
        Console.WriteLine($"Operation completed.\nPress enter to exit.");
      };
      xmodem.Aborted += (s,e) => {
        Console.WriteLine("Operation Aborted.\nPress enter to exit.");
      };
      
      // Open port for use.
      port.Open();

      Console.WriteLine("Awaiting Receiver. Press enter to cancel.");
      // Send Data.
      xmodem.Send();
  
      // Await user.
      Console.ReadLine();
  
      if (xmodem.State != XModemStates.Idle) {
        xmodem.CancelOperation();
        Console.ReadLine();
      }
      
      // Dispose of port.
      port.Close();
    }
  }
}

Simple Receive Example

using XModemProtocol;
using System;
using System.IO.Ports;
using System.IO;
using System.Linq;

namespace XModemProtocolExample {

  class Program {

    static void Main(string[] args) {
  
      Console.WriteLine("XModemProtocol Receive Example\n");
  
      // Set up Port.
      var port = new SerialPort{
        BaudRate = 230400,
        DataBits = 8,
        Parity = Parity.Even,
        StopBits = StopBits.One,
        PortName = "COM5",
      };
  
      // Instantiate XModemCommunicator.
      var xmodem = new XModemCommunicator();
  
      // Attach port.
      xmodem.Port = port;
  
      // Subscribe to events.
      xmodem.Completed += (s,e) => {
        string message = "";
        try {
          File.WriteAllBytes(@"C:\fileReceived.hex", e.Data.ToArray());
          message = "Operation completed. Bytes written to file.";
        }
        catch {
          message = "Problem writing to file.";
        }
        Console.WriteLine($"{message}\nPress enter to exit.");
      };
      xmodem.Aborted += (s,e) => {
        Console.WriteLine("Operation Aborted.\nPress enter to exit.");
      };
      
      // Open port for use.
      port.Open();
  
      // Receive Data.
      Console.WriteLine("Receive Operation beginning. Press enter to cancel.");
      xmodem.Receive();
  
      // Await user.
      Console.ReadLine();
  
      if (xmodem.State != XModemStates.Idle) {
        xmodem.CancelOperation();
        Console.ReadLine();
      }
      
      // Dispose of port.
      port.Close();
    }
  }
}

Author

Peter T. Owens-Finch
powensfinch@gmail.com

VMKReddy/XmodemProtocol