mapache

README

mapache-go

mapache-go is a library that provides access to various abstractions used by Mapache services.

Getting started

Prerequisites

mapache-go requires Go version 1.21 or above.

Installing

With Go's module support, go [build|run|test] automatically fetches the necessary dependencies when you add the import in your code:

import "github.com/gaucho-racing/mapache-go"

Alternatively, use go get:

go get -u github.com/gaucho-racing/mapache-go

Contributing

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b gh-username/my-amazing-feature)
3. Commit your Changes (git commit -m 'Add my amazing feature')
4. Push to the Branch (git push origin gh-username/my-amazing-feature)
5. Open a Pull Request

Documentation

Index

• func BigEndianBytesToSignedInt(bytes []byte) int
• func BigEndianBytesToUnsignedInt(bytes []byte) int
• func BigEndianSignedIntToBinary(num int, numBytes int) ([]byte, error)
• func BigEndianSignedIntToBinaryString(num int, numBytes int) (string, error)
• func BigEndianUnsignedIntToBinary(num int, numBytes int) ([]byte, error)
• func BigEndianUnsignedIntToBinaryString(num int, numBytes int) (string, error)
• func LittleEndianBytesToSignedInt(bytes []byte) int
• func LittleEndianBytesToUnsignedInt(bytes []byte) int
• func LittleEndianSignedIntToBinary(num int, numBytes int) ([]byte, error)
• func LittleEndianSignedIntToBinaryString(num int, numBytes int) (string, error)
• func LittleEndianUnsignedIntToBinary(num int, numBytes int) ([]byte, error)
• func LittleEndianUnsignedIntToBinaryString(num int, numBytes int) (string, error)
• type Endian
• type ExportSignalFunc
• type Field
  • func NewField(name string, size int, sign SignMode, endian Endian, ...) Field
  • func (f Field) CheckBit(bit int) int
  • func (f Field) Decode() Field
  • func (f Field) Encode() (Field, error)
  • func (f Field) ExportSignals() []Signal
• type Lap
  • func (Lap) TableName() string
• type Message
  • func (m Message) ExportSignals() []Signal
  • func (m Message) FillFromBytes(data []byte) error
  • func (m Message) FillFromInts(ints []int) error
  • func (m Message) Length() int
  • func (m Message) Size() int
• type Ping
  • func (Ping) TableName() string
• type SignMode
• type Signal
  • func DefaultSignalExportFunc(f Field) []Signal
  • func (Signal) TableName() string
• type Trip
  • func (Trip) TableName() string
• type Vehicle
  • func (Vehicle) TableName() string

Functions

func BigEndianBytesToSignedInt

func BigEndianBytesToSignedInt(bytes []byte) int

BigEndianBytesToSignedInt converts bytes to a signed integer in big endian format.

The function returns the integer value of the bytes.

func BigEndianBytesToUnsignedInt

func BigEndianBytesToUnsignedInt(bytes []byte) int

BigEndianBytesToUnsignedInt converts bytes to an unsigned integer in big endian format.

The function returns the integer value of the bytes.

func BigEndianSignedIntToBinary

func BigEndianSignedIntToBinary(num int, numBytes int) ([]byte, error)

BigEndianSignedIntToBinary converts a signed integer to bytes in big endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a slice of bytes representing the binary.

func BigEndianSignedIntToBinaryString

func BigEndianSignedIntToBinaryString(num int, numBytes int) (string, error)

BigEndianSignedIntToBinaryString converts a signed integer to a binary string in big endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a string of 0s and 1s representing the binary.

func BigEndianUnsignedIntToBinary

func BigEndianUnsignedIntToBinary(num int, numBytes int) ([]byte, error)

BigEndianUnsignedIntToBinary converts an unsigned integer to bytes in big endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a slice of bytes representing the binary.

func BigEndianUnsignedIntToBinaryString

func BigEndianUnsignedIntToBinaryString(num int, numBytes int) (string, error)

BigEndianUnsignedIntToBinaryString converts an unsigned integer to a binary string in big endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a string of 0s and 1s representing the binary.

func LittleEndianBytesToSignedInt

func LittleEndianBytesToSignedInt(bytes []byte) int

LittleEndianBytesToSignedInt converts bytes to a signed integer in little endian format.

The function returns the integer value of the bytes.

func LittleEndianBytesToUnsignedInt

func LittleEndianBytesToUnsignedInt(bytes []byte) int

LittleEndianBytesToUnsignedInt converts bytes to an unsigned integer in little endian format.

The function returns the integer value of the bytes.

func LittleEndianSignedIntToBinary

func LittleEndianSignedIntToBinary(num int, numBytes int) ([]byte, error)

LittleEndianSignedIntToBinary converts a signed integer to bytes in little endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a slice of bytes representing the binary.

func LittleEndianSignedIntToBinaryString

func LittleEndianSignedIntToBinaryString(num int, numBytes int) (string, error)

LittleEndianSignedIntToBinaryString converts a signed integer to a binary string in little endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a string of 0s and 1s representing the binary.

func LittleEndianUnsignedIntToBinary

func LittleEndianUnsignedIntToBinary(num int, numBytes int) ([]byte, error)

LittleEndianUnsignedIntToBinary converts an unsigned integer to bytes in little endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a slice of bytes representing the binary.

func LittleEndianUnsignedIntToBinaryString

func LittleEndianUnsignedIntToBinaryString(num int, numBytes int) (string, error)

LittleEndianUnsignedIntToBinaryString converts an unsigned integer to a binary string in little endian format. The input num will be packed into a number of bytes specified by length. If num is too large to fit in length bytes, an error will be returned.

The function returns a string of 0s and 1s representing the binary.

Types

type Endian

type Endian int

Endian is a type to represent whether an integer is big endian or little endian.

const (
	BigEndian    Endian = 1
	LittleEndian Endian = 0
)

type ExportSignalFunc

type ExportSignalFunc func(Field) []Signal

ExportSignalFunc is a function that indicates how a field should be exported as an array of signals. Any required scaling will be applied here. If ExportSignalFunc is not set, the field will be directly exported as a single signal without scaling.

type Field

type Field struct {
	// Name of the field. Will be mapped to a signal name unless otherwise specified by ExportSignalFunc.
	Name string
	// Bytes, Size, Sign, and Endian are used to properly decode and encode the signal.
	Bytes  []byte
	Size   int
	Sign   SignMode
	Endian Endian
	// Value is the integer value of the field.
	Value int
	// ExportSignalFunc is the function that is used to export the field as an array of signals.
	ExportSignalFunc ExportSignalFunc
}

Field is a single field of a message. It will always be at least 1 byte in size. It is meant to be an intermediary structure, purely for encoding and decoding byte arrays. A single field may contain multiple signals (tpyically when it contains multiple errors as boolean flags).

func NewField

func NewField(name string, size int, sign SignMode, endian Endian, exportSignalFunc ExportSignalFunc) Field

NewField creates a new Field object with the given name, size, sign, endian, and export function. If no export function is provided, DefaultSignalExportFunc will be used.

func (Field) CheckBit

func (f Field) CheckBit(bit int) int

CheckBit takes a Field object and a bit position, and returns the integer value of the bit at the given position (0 or 1). Bit positions are counted from left to right, where bit 0 is the leftmost bit.

func (Field) Decode

func (f Field) Decode() Field

Decode takes a Field object, decodes the bytes into an integer value, and returns the decoded Field object.

func (Field) Encode

func (f Field) Encode() (Field, error)

Encode takes a Field object, encodes the integer value into bytes, and returns the encoded Field object.

func (Field) ExportSignals

func (f Field) ExportSignals() []Signal

ExportSignals takes a Field object and exports it as an array of signals.

type Lap

type Lap struct {
	// ID is a unique identifier for the lap.
	ID string `json:"id" gorm:"primaryKey"`
	// The TripID is the unique identifier for the trip that the lap is associated with.
	TripID string `json:"trip_id"`
	// The Name is the public-facing name of the lap.
	Name string `json:"name"`
	// The Timestamp is the time at which the lap segment is over.
	// The start time of the lap would be inferred from the previous lap's end time
	// or the beginning of the trip.
	Timestamp time.Time `json:"timestamp" gorm:"precision:6"`
}

func (Lap) TableName

func (Lap) TableName() string

type Message

type Message []Field

A Message is a single data message from a vehicle, comprised of a list of Fields.

func (Message) ExportSignals

func (m Message) ExportSignals() []Signal

ExportSignals returns a list of all Signals contained in each Field of the Message. Basically just calls ExportSignals on each Field and concatenates the results.

func (Message) FillFromBytes

func (m Message) FillFromBytes(data []byte) error

FillFromBytes fills the Fields of a Message with the provided byte array. It decodes the bytes into integer values and stores them in the Value of each Field. It returns an error if the data length does not match the size of the Message.

func (Message) FillFromInts

func (m Message) FillFromInts(ints []int) error

FillFromInts fills the Fields of a Message with the provided integers. It encodes the integers into bytes and stores them in the Bytes of each Field. It returns an error if the number of integers does not match the number of Fields in the Message.

func (Message) Length

func (m Message) Length() int

Length returns the number of fields in the message.

func (Message) Size

func (m Message) Size() int

Size returns the total number of bytes in the message.

type Ping

type Ping struct {
	// VehicleID is the unique identifier for the vehicle that sent the ping.
	VehicleID string `json:"vehicle_id" gorm:"primaryKey"`
	// Ping is the unix millis when the vehicle sent the ping.
	Ping int `json:"ping" gorm:"primaryKey"`
	// Pong is the unix millis when the vehicle received the ping.
	Pong int `json:"pong"`
	// Latency is the latency of the ping in milliseconds.
	Latency int `json:"latency"`
}

Ping is a type to represent a ping between the vehicle and the server. Note that only the uplink latency is saved on the server. The vehicle does receive pongs, so it may choose to record the round trip time if it desires.

func (Ping) TableName

func (Ping) TableName() string

type SignMode

type SignMode int

SignMode is a type to represent whether an integer is signed or unsigned.

const (
	Signed   SignMode = 1
	Unsigned SignMode = 0
)

type Signal

type Signal struct {
	// Timestamp is the Unix milliseconds of the signal.
	Timestamp int `json:"timestamp"`
	// VehicleID is the unique identifier for the vehicle that the signal is associated with.
	VehicleID string `json:"vehicle_id"`
	// Name represents the name of the signal.
	Name string `json:"name"`
	// Value is the value of the signal post-scaling.
	Value float64 `json:"value"`
	// RawValue is the raw value of the signal before scaling.
	RawValue int `json:"raw_value"`
	// ProducedAt is the time at which the signal was produced by the vehicle.
	ProducedAt time.Time `json:"produced_at" gorm:"precision:6"`
	// CreatedAt is the time at which the signal was actually stored in the database.
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime;precision:6"`
}

Signal is a type to represent an individual signal coming from the vehicle. This can be something like a sensor reading, a boolean flag, or a status code. Timestamp, VehicleID, and Name are together used to uniquely identify a signal row entry.

func DefaultSignalExportFunc

func DefaultSignalExportFunc(f Field) []Signal

DefaultSignalExportFunc is the default export function for a field. It exports the field as a single signal with no scaling.

func (Signal) TableName

func (Signal) TableName() string

type Trip

type Trip struct {
	// ID is a unique identifier for the trip.
	ID string `json:"id" gorm:"primaryKey"`
	// The VehicleID is the unique identifier for the vehicle that the trip is associated with.
	VehicleID string `json:"vehicle_id"`
	// The Name is the public-facing name of the trip.
	Name string `json:"name"`
	// The Description is a brief description of the trip. This can include any notes or comments.
	// In theory, would be a markdown-supported field.
	Description string `json:"description"`
	// The StartTime is the time at which the trip started.
	StartTime time.Time `json:"start_time" gorm:"precision:6"`
	// The EndTime is the time at which the trip is over.
	EndTime time.Time `json:"end_time" gorm:"precision:6"`
	// The Laps field is a list of laps that are associated with the trip.
	// Laps are essentially markers that separate the trip into smaller segments.
	Laps []Lap `json:"laps" gorm:"-"`
}

func (Trip) TableName

func (Trip) TableName() string

type Vehicle

type Vehicle struct {
	// ID is a unique identifier for the vehicle.
	ID string `json:"id" gorm:"primaryKey"`

	// The Name is the public-facing name of the vehicle.
	Name string `json:"name"`

	// The Description is a brief description of the vehicle.
	Description string `json:"description"`

	// The Type is the type of vehicle, usually the year classification (gr23, gr24, etc).
	// This is used to identify the vehicle's controller architecture.
	Type string `json:"type"`

	// The UploadKey is a unique identifier for the vehicle's uploaded files.
	// This is used to authenticate the vehicle when processing uploaded data.
	UploadKey int `json:"upload_key"`

	UpdatedAt time.Time `json:"updated_at" gorm:"autoUpdateTime;precision:6"`
	CreatedAt time.Time `json:"created_at" gorm:"autoCreateTime;precision:6"`
}

func (Vehicle) TableName

func (Vehicle) TableName() string