SystemK/Protocols/Protocols.h

/*
 * This program source code file is part of SystemK, a library in the KTag project.
 *
 * 🛡️ <https://ktag.clubk.club> 🃞
 *
 * Copyright © 2016-2025 Joseph P. Kearney and the KTag developers.
 *
 * This program is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Affero General Public License as published by the Free
 * Software Foundation, either version 3 of the License, or (at your option) any
 * later version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more
 * details.
 *
 * There should be a copy of the GNU Affero General Public License in the LICENSE
 * file in the root of this repository.  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef PROTOCOLS_H
#define PROTOCOLS_H

#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>

#define FOREACH_PROTOCOL(PROTOCOL)        \
    PROTOCOL(UNKNOWN_PROTOCOL)            \
    PROTOCOL(TEST_PROTOCOL)               \
    PROTOCOL(DUBUQUE_PROTOCOL)            \
    PROTOCOL(MILES_TAG_II_PROTOCOL)       \
    PROTOCOL(NERF_LASER_OPS_PRO_PROTOCOL) \
    PROTOCOL(NERF_LASER_STRIKE_PROTOCOL)  \
    PROTOCOL(NERF_PHOENIX_LTX_PROTOCOL)   \
    PROTOCOL(DYNASTY_PROTOCOL)            \
    PROTOCOL(SQUAD_HERO_PROTOCOL)         \
    PROTOCOL(NEC_PROTOCOL)                \
    PROTOCOL(LASER_X_PROTOCOL)            \
    PROTOCOL(LAST_PROTOCOL)

#define GENERATE_ENUM(ENUM) ENUM,
#define GENERATE_STRING(STRING) #STRING,

typedef enum
{
    FOREACH_PROTOCOL(GENERATE_ENUM)
} Protocol_T;

#define MAX_PULSES 125
#define LAST_PULSE 0

typedef enum
{
    FREQUENCY_38kHz,
    FREQUENCY_56kHz
} ModulationFrequency_T;

//! On-Off Keying (OOK) symbols
typedef enum
{
    SPACE = 0,
    MARK = 1
} OOK_Symbol_T;

//! Represents a length of time, in microseconds.
typedef uint32_t Duration_in_us_T;

typedef enum
{
    TAG_SENSOR_UNKNOWN = 0,
    TAG_SENSOR_NONE,
    TAG_SENSOR_FORWARD,
    TAG_SENSOR_LEFT,
    TAG_SENSOR_RIGHT,
    TAG_SENSOR_REMOTE
} TagSensorLocation_T;

typedef struct
{
    //! Use a value of #LAST_PULSE to mean the pulsetrain is over.
    Duration_in_us_T duration : 15;
    OOK_Symbol_T symbol : 1;
} __attribute__((packed)) TimedBit_T;

//! Timing information for a single pulse, packed into a 32-bit integer.
/*
 *  \see #rmt_item32_t in the ESP-IDF.
 */
typedef struct
{
    union
    {
        struct
        {
            Duration_in_us_T duration0 : 15;
            OOK_Symbol_T symbol0 : 1;
            Duration_in_us_T duration1 : 15;
            OOK_Symbol_T symbol1 : 1;
        };
        uint32_t val;
    };
} __attribute__((packed)) TimedPulse_T;

typedef struct
{
    union
    {
        TimedPulse_T pulsetrain[MAX_PULSES];
        TimedBit_T bitstream[2 * MAX_PULSES];
    };
    uint16_t count;
    TagSensorLocation_T receiver;
} __attribute__((packed)) TimedPulseTrain_T;

typedef enum
{
    DECODED_PACKET_TYPE_BUFFER_FREE,
    DECODED_PACKET_TYPE_UNKNOWN,
    DECODED_PACKET_TYPE_IGNORED,
    DECODED_PACKET_TYPE_TAG_RECEIVED,
    DECODED_PACKET_TYPE_COMMAND_RECEIVED
} DecodedPacketType_T;

typedef struct
{
    DecodedPacketType_T type;
    TagSensorLocation_T receiver;
    uint8_t protocol;
} GenericDecodedPacket_T;

//! Contents of the decoded packet #DECODED_PACKET_TYPE_TAG_RECEIVED.
typedef struct
{
    DecodedPacketType_T type;
    TagSensorLocation_T receiver;
    uint8_t protocol;
    uint16_t team_ID;
    uint16_t player_ID;
    uint16_t damage;
    color_t color;
} TagPacket_T;

//! Contents of the decoded packet #DECODED_PACKET_TYPE_COMMAND_RECEIVED.
typedef struct
{
    DecodedPacketType_T type;
    TagSensorLocation_T receiver;
    uint8_t protocol;
    uint16_t command;
    uint32_t data;
} CommandPacket_T;

typedef union
{
    GenericDecodedPacket_T Generic;
    TagPacket_T Tag;
    CommandPacket_T Command;
} DecodedPacket_T;

static inline void FreeDecodedPacketBuffer(DecodedPacket_T *buffer)
{
    if (buffer != NULL)
    {
        buffer->Generic.type = DECODED_PACKET_TYPE_BUFFER_FREE;
    }
}

ModulationFrequency_T PROTOCOLS_GetModulationFrequency(Protocol_T protocol);
color_t PROTOCOLS_GetColor(Protocol_T protocol, uint8_t team_ID, uint8_t player_ID);
TimedPulseTrain_T *PROTOCOLS_EncodePacket(TagPacket_T *packet);
DecodedPacket_T *PROTOCOLS_MaybeDecodePacket(TimedPulseTrain_T *packet);

// Include the supported protocols.
#include "Test.h"
#include "Dubuque.h"
#include "Miles_Tag_II.h"
#include "NEC.h"
#include "Nerf_Laser_Ops_Pro.h"
#include "Nerf_Laser_Strike.h"
#include "Nerf_Phoenix_LTX.h"
#include "Dynasty.h"
#include "Squad_Hero.h"
#include "Laser_X.h"

#endif // PROTOCOLS_H