starpeng/XmodemProtocol

Implementation of XMODEM Protocol

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

• 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

• Write Only

• 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.

• Values

• Checksum => Normal XModem mode packet size of 128 using simple checksum.

• CRC => Normal XModem packet size of 128 using CRC.

• OneK => Implementation of XModem-1k.

Methods

• Send
  Puts XModemProtocol.XModemCommuniator in the sender role awaiting initialization byte from receiver.

• Receive
  Puts XModemProtocol.XModemCommuniator in the receiver role sending the initialization byte.

• 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.

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.GetAllBytes(@"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.");
      };

      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();
      }
    }
  }
}

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.");
      };
  
      // 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();
      }      
    }
  }
}

Author

Peter T. Owens-Finch
powensfinch@gmail.com