eyecan-shiva 0.6.0

Shiva Communication Protocol

Shiva

Table of contents

• Shiva
  • Table of contents
  • Introduction
    • Message
    • Chunks
      • Magic Number & CRC
  • Data
    • Metadata
    • Namespace (aka. Command)
    • Tensor
  • Examples
  • :whale2: Docker

Introduction

Message

The Shiva Message is a binary flow of the following chunks:

The protocol is based on a 'Send Message / Receive Message' flow. For each message sent from the client, the server will respond synchronously with another message. The format of the message is detailed in the following section, the content of the variable part of the message, i.e., tensors/metadata/namespace, is determined by the business logic and can be any data the application requires.

Chunks

Message chunks are made as follows:

:warning: All integers (uint32) in headers as well as tensors data are encoded in big endian during send and receive.

Magic Number & CRC

The magic number serves as a signal lock; it can be valuable in a byte streaming channel to indicate the start of a message. In the current implementation, the magic number is composed of 4 unsigned bytes: (6, 66, 11, 1).

The double CRC at the end of the header is useful for checking and validating the content of the header. Both CRCs are unsigned bytes, and their values are the sum modulo 256 of the preceding numbers. See python implementation for an example

Data

Metadata

The metadata is a generic JSON string.

Namespace (aka. Command)

The namespace is a generic string that can be used, for example, to route the message to the right handler.

Tensor

Each tensor can be a multi-dimensional array of any type. Hence, the tensor has a rank, a shape and a type. The rank is the number of dimensions, the shape is a list of integers, one per dimension, and the type is a string that can be one of the following map:

{
    float16: 0,
    float32: 1,
    uint8: 3,
    int8: 4,
    uint16: 5,
    int16: 6,
    uint32: 7,
    int32: 8,
    uint64: 9,
    int64: 10,
    double: 11,
    longdouble: 12,
    longlong: 13,
    complex64: 14,
    complex128: 15,
    bool: 17,
}

For example a (h,w,c) image of 8-bit unsigned integers will have a rank of 3, a shape of [h,w,c] and a type of 3 (uint8).

Examples

See Examples.

:whale2: Docker

To build the shiva image:

cd shiva/
docker build -f dockerfiles/Dockerfile -t shiva:latest .

To start a CLI session just run the provided compose:

docker compose -f dockerfiles/docker-compose.cli.yml run --service-ports --rm cli