This articles guides through using Hexabitz HexInterface library-a .Net library that facilitates communications with Hexabitz modules in your C# and other .Net software via a serial virtual COM port.

Hexabitz .Net Communication Library

The following documentation is about connecting and interacting with Hexabitz modules using .Net framework.

The library contains two classes:

Message.cs

This class represents the message array class to be sent to Hexabitz modules that contains the required bytes (H | Z | Length | Destination | Source | Options | Code | Par. 1 | Par. 2 | ——- | CRC8) where (Par. 1 | Par. 2 | ——-) are the parameters for the payload. For more info about the Array messaging visit this Wiki article. 

The class contains the following methods:

• Public Message (byte Destination, byte Source, byte Options, int Code, byte[] Payload)
  The main constructor for the message with the parameters:
  • Source and Destination are IDs of source and destination modules.
  • Options: is a byte that contains some option bits and flags.
  • Code: Is a 16-bit variable representing Message Codes.
  • Payload: The data we want to send to the Hexabitz modules.
  • And for each Message there is a CRC in the last byte to check the integrity of the message array.
• public byte GetCRC(): Method to calculate the CRC (Cyclic redundancy check) for the message array.
• public byte[] GetAll(): Method to get the full message bytes.
• private List<byte> Organize(List<byte> MesssageList): Private method to organize the message bytes in the correct order as described here in Calculating and Comparing CRC Codes section.
• private byte CRC32B(byte[] Buffer): Algorithm used at Hexabitz modules hardware to calculate the correct CRC32, but we are only using the first byte in our modules.

HexInterface.cs

Which will represent the Interface between the Message Class and the platform we are going to connect the Hexabitz modules with. Here we are using .Net and C# programming language.

The class contains the following methods:

• public HexaInterface(string COM): To initialize an instance providing COM number only.
• Start() and End(): to open and close the Serial port.
• public byte Options(): To create the options’ byte.
• public void SendMessage(byte Destination, byte Source, byte Options, int Code, byte[] Payload): The parameters are:
  • Source and Destination are IDs of source and destination modules.
  • Options: is a byte that contains some optional bits and flags.
  • Message: The data we want to send to Hexabitz modules in the correct order according to its functionality.
• private void Receive(): The receiving method to listen to the port if we got any response from it.
• private void Port_DataReceived(object sender, SerialDataReceivedEventArgs e): Method that .Net platform provides to respond to the received data from the Serial Port.
• private string to_right_hex(string hex): To correct the values received from the port.
• A section for options byte enums in Options section.
• And also it contains message codes enum to specify the target codes used in the communication.

Usage

Sending

The Message class is the base class to create the right message with its CRC, but the HexInterface class can be modified according to the platform you are willing to use with Hexabitz modules. Here is an example of using and implementing the library using C# language.

First, create an example of the HexInterface and give it a string represents the COM port number you are using.

HexaInterface HexInter = new HexaInterface("5");

Or if we want to get it for instance from a ComboBox value using windows forms:

HexaInterface HexInter = new HexaInterface(COM.Value.ToString());

To send a message with the payload (see documentation for correct bytes order):

HexInter.SendMessage(Destination, Source, Options, Code, Payload);

But before sending the message we must construct the Options byte using HexaInterface.Options()

 public byte Options (Options1_Extended_Flag options1_Extended_Flag,
                                Options2_16_BIT_Code options2_16_BIT_Code,
                                Options34_Trace_Options options34_Trace_Options,
                                Options5_Reserved options5_Reserved,
                                Options67_Response_Options options67_Response_Options,
                                Options8_Next_Message options8_Next_Message) 
        {
            string optionsString = "" + options1_Extended_Flag +
                                        options2_16_BIT_Code +
                                        options34_Trace_Options +
                                        options5_Reserved +
                                        options67_Response_Options +
                                        options8_Next_Message;

            char[] charArray = optionsString.ToCharArray();
            Array.Reverse(charArray);
            optionsString = new string(charArray);
            return byte.Parse(optionsString);
        }

Where the options are enum as described about the parameters above, we have the Payload array must be constructed in the right order to get the modules to do their right job.
The following example is about communicating with the H26R0x module to send and receive data from it:
We have two variables, Period and Time with a data type : uint

We are going to get the 4 byte array for them (C#):

byte[] PeriodBytes = BitConverter.GetBytes(period);
byte[] TimeBytes = BitConverter.GetBytes(time);

And we’ve got also (for this example) Channel, PortModule and Module as bytes to be included in the Payload array, so the final will be:

byte[] Payload = {
                channel,
                periodBytes[3],
                periodBytes[2],
                periodBytes[1],
                periodBytes[0],

                timeBytes[3],
                timeBytes[2],
                timeBytes[1],
                timeBytes[0],

                modulePort,
                module};

Now we can call the SendMessage with the correct Options and Payload.

Receiving

Receiving bytes from a serial port is platform-dependent. We’ll show in the following examples how to receive and parse a 4 byte float value using the HexInterface Receive method.

Here we have the Receive method:

// The receiving method to listen to the port if we got any respond from it.
    private void Receive()
    {
        Port.DataReceived += new SerialDataReceivedEventHandler(Port_DataReceived);
        try { Port.Open(); } catch { }
    }

Where Port is defined as:
SerialPort = new SerialPort("COM" + COM, 921600, Parity.None, 8, StopBits.One); // The default values to be used in the connection.

And Port_DataReceived is defined as:

// Method the .Net platform provids to responed to recieved data from SerialPort.
    private void Port_DataReceived(object sender, SerialDataReceivedEventArgs e)
    {
        int bytes_count = 0;
        byte[] buffer = new byte[4];
        bytes_count = Port.Read(buffer, 0, 4);

        string D0 = to_right_hex(buffer[3].ToString("X"));
        string D1 = to_right_hex(buffer[2].ToString("X"));
        string D2 = to_right_hex(buffer[1].ToString("X"));
        string D3 = to_right_hex(buffer[0].ToString("X"));
        string value = D3 + D2 + D1 + D0;

        int IntRep = int.Parse(value, NumberStyles.AllowHexSpecifier); // here is the representation of the value in Integer value
        float FloatRep = BitConverter.ToSingle(BitConverter.GetBytes(IntRep), 0); // convert the int value to float
        
    }

Where to_right_hex is defined as:

// To correct the values recieved from the port.
        private string to_right_hex(string hex)
        {
            switch (hex)
            {
                case "A": hex = "0" + hex; break;
                case "B": hex = "0" + hex; break;
                case "C": hex = "0" + hex; break;
                case "D": hex = "0" + hex; break;
                case "E": hex = "0" + hex; break;
                case "F": hex = "0" + hex; break;
            }
            return hex;
        }