Need help understanding the protocol, for a custom program that needs to light up LEDs directly

[davthedev]

My real interest for the project is that I was looking for a simple way to control RGB LEDs from a custom computer program. I am developing a video game that should light up some LEDs at defined moments, and need good enough bandwidth to enable smooth animations.
Seems that HyperSerial devices with the AWA protocol is the only out-of-the-box solution I found that is technically capable of that.

I have set up an ItsyBitsy RP2040 with HyperSerialPico to light up 256 LEDs, and made a custom PCB to plug in a barrel-jack power supply. When I run the thing through HyperHDR or hyperion-ng, this works great, even using a 5V 5A wall wart to power the LEDS. There seems some nice current-limiting logic built-in in the HyperHDR software, which is great, as running all my LEDs at full current in such a setup makes a brown-out down the strip and puts too much strain on the power supply.

The next step is to understand the protocol so that my game can directly talk to HyperSerialPico and literally speak AWA.
I did a try in Python to reverse engineer the protocol - below is a code sample - to replicate what I understood from it based on the source code. One difficulty was to correctly compute the checksums, both for the header and the whole packet.

When I run the code, I get mixed results. For example, it may take 2-3 attempts to light up the LEDs. Or I may need to male a run of HyperHDR in between that seems to perform some handshake and put the device in a good state before. If I run a loop to simulate a smooth animation, after a dozen frames, the RP2040 goes in "PANIC", saying "No space left for program" or something similar, on the serial line, and freezes. Or it may simply hang when I attempt to read bytes from the serial port. I need to disconnect and reconnect the USB cable to rearm the device when this happens. Those issues are frequent and random.

I may try with something else than Python because the pyserial library has reports of issues about cleaning up or resetting the TX/RX buffers at some moments.

There is something I did not understand with the protocol or I am missing, as HyperHDR / hyperion-ng makes the lights still work perfectly. My open questions are:

• Which settings for the serial port other than the 2000000 bauds? Number of bits, parity, stop bit, etc...
• Is there some handshake or ack that must be done at the beginning and between the packets? My attempts to read the incoming data give no output, apart from the "PANIC" situation.

Below is my Python code I used for my experiments.

import serial
import random

def send_leds(ser, count):
    random_byte1 = random.randint(0, 40)
    random_byte2 = random.randint(0, 40)
    random_byte3 = random.randint(0, 40)

    color_set = [
        random_byte1, random_byte2, random_byte3
    ]

    #color_set = [0x00, 0x30, 0x10]

    data_bytes = color_set * count

    #header_bytes = [0x41, 0x77, 0x61, 0x00, 0x03, 0x56]
    header_bytes = [0x41, 0x77, 0x61, 0x00, 0x00, 0x00]

    led_send_count = len(data_bytes) // 3 - 1

    header_len_hi = led_send_count >> 8
    header_len_lo = led_send_count & 0xFF
    header_checksum = header_len_hi ^ header_len_lo ^ 0x55

    header_bytes[3] = header_len_hi
    header_bytes[4] = header_len_lo
    header_bytes[5] = header_checksum

    #print("Header (hex): ", [hex(byte) for byte in header_bytes])

    # Define the hex string as bytes
    awa_protocol_bytes = header_bytes + \
    data_bytes + \
    [0x00, 0x00, 0x00]

    # Recompute the Fletcher checksum

    # Initialize the checksum variables
    sum1 = 0
    sum2 = 0
    sum_ext = 0
    sum_position = 0

    # Loop through the bytes from index 6 to (length - 3)


    for byte in awa_protocol_bytes[6:-3]:
        sum1 = (sum1 + byte) % 255
        sum2 = (sum2 + sum1) % 255
        sum_ext = (sum_ext + (byte ^ sum_position)) % 255

        sum_position = sum_position + 1
        if sum_position > 255:
            sum_position -= 256


    #print("Cycled positions: ", sum_position)

    # Append the checksum to the protocol bytes
    awa_protocol_bytes[-3] = sum1
    awa_protocol_bytes[-2] = sum2
    awa_protocol_bytes[-1] = sum_ext if sum_ext != 0x41 else 0xAA

    #print("Checksums: ", hex(sum1), hex(sum2), hex(sum_ext))

    print("Full bytes (hex):", ''.join(f'{byte:02x}' for byte in awa_protocol_bytes))

    if ser.in_waiting > 0:
        response = ser.read(ser.in_waiting)
        print(f"Pre read: {response}")

    ser.write(bytes(awa_protocol_bytes))
    if ser.in_waiting > 0:
        response = ser.read(ser.in_waiting)
        print(f"Post read: {response}")
    #ser.close()
    ser.reset_input_buffer()
    ser.reset_output_buffer()

    #print("Done")


ser = serial.Serial('/dev/ttyACM0', 2000000, timeout=1)

leds_count = 8
print(f"Sending {leds_count} LEDs")
send_leds(ser, leds_count)

ser.close()

print("Done")

[awawa-dev]

Hi
If you don't need this then I would completely avoid reading from serialports while running (sending colors to the device). You are missing a flush() function on the serialport after you have written data. Try adding it and see if it helps. Serial port speed is usually irrelevant for CDC devices like Pico: leave it at 2000000.

[awawa-dev]

I rarely use Python, but this was suggested by ChatGPT for fletcher checksum (but your version is probably also good, I dont know ;) ):

def fletcher_checksum(data: bytearray, start: int, end: int):
    fletcher1 = 0
    fletcher2 = 0
    fletcher_ext = 0
    position = 0

    current_index = start
    while current_index < end:
        current_byte = data[current_index]
        fletcher_ext = (fletcher_ext + (current_byte ^ position)) % 255
        fletcher1 = (fletcher1 + current_byte) % 255
        fletcher2 = (fletcher2 + fletcher1) % 255
        position += 1
        current_index += 1

    # Append the checksums to the specified positions in the data
    data[end] = fletcher1
    data[end + 1] = fletcher2
    data[end + 2] = fletcher_ext if fletcher_ext != 0x41 else 0xAA

# Example usage:
led_buffer = bytearray(100)

# Call fletcher_checksum on the desired range, skip header (6), target 3 bytes from the end
fletcher_checksum(led_buffer, 6, 97)

[davthedev]

The flush is happening already! Just that the method is not called flush() anymore (deprecated) but reset_input_buffer() and reset_output_buffer().

In the meantime, I ported the handshake code and this made the difference. Works like a charm now!

Just need to call this right after opening the serial port. Inspired from https://github.com/awawa-dev/HyperHDR/blob/b125da90909d00645e8b7af12fd6f41fccbc0c92/include/led-drivers/serial/EspTools.h#L40

def send_initialization(ser):

    init_buffer = [ 0x41, 0x77, 0x41, 0x2a, 0xa2, 0x15, 0x68, 0x79, 0x70, 0x65, 0x72, 0x68, 0x64, 0x72 ]

    written_count = ser.write(bytes(init_buffer))
    print(f"Wrote {written_count} bytes")

    print("Resetting")

    ser.dtr = True
    ser.rts = True
    ser.rts = False

    time.sleep(0.1)

    print("Getting handshake")
    if ser.in_waiting > 0:
        response = ser.read(ser.in_waiting)
        print("Got a response")
        print(response)

By the way, what is the purpose of this specific byte sequence during the initialization? Magic code to reset the device?

[awawa-dev]

This is strictly for use by HyperHDR to read statistics. Since you tested this with Hyperion, which doesn't use it, it's not critical.