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