Draft of register specification

[bruno-f-cruz]

Period generation of messages (Timer)

Sends out periodic messages eg. 250hz (1 register for Event U32 counter, 1 Register for writing period/frequency)

e.g.:

 Timer:
    address: 33
    type: U32
    access: [Write, Event]
    description: Unitary counter that periodically produces a value at the frequency defined by register TimerFrequency.
  TimerFrequency:
    address: 34
    type: U8
    access: Write
    maskType: TimerRate
    description: Frequency at which the Timer will generate new values.

IsConnected.

U16 > each bit is a device/port connected(1) or not (0). Emit a message each time it changes. eg.:

 DevicesConnected:
    address: 32
    type: U8
    access: Read
    maskType: ConnectedDevices
    description: Specifies which CLK_OUT ports have devices connected.

Writable Seconds register

Low 1kpbs / PPS

[Poofjunior]

Ok, can I propose a few changes?

• 32: connected_devices instead of DevicesConnected
• 33: heartbeat or heartbeat_counter instead of Timer (Heartbeat has a standard meaning.)
• 34: heartbeat_frequency_hz instead of TimerFrequency
• 34: U16 instead of U8 and the value 0 - 1000 represents the actual publish rate instead of an enum of predefined values.

[bruno-f-cruz]

I am fine with connected_devices as long as it is pascal casing :P

33 and 34 i really don't think we should call it heartbeat. For two reasons. 1) this register is not reporting the state of the device it is really just a "dumb" periodic event. 2) I think heartbeat is already co-opted by a recent proposal: https://github.com/harp-tech/protocol/pull/45

[Poofjunior]

If not heartbeat, how about counter then?

Since these are scoped to Core and App registers, I'm totally ok with having overlapping names--especially since all core registers are prefixed with R_.

[bruno-f-cruz]

Sure, the counter is ok. My only contention is whether to try to align interfaces across different devices if possible, as to only ask users to learn a single name, but if we want to go with something different i don't have a strong opinion. Counter sounds good.

Regarding the names, the decision is a bit more complicated. Since the bonsai/python interfaces are generated from the yml file, it is critical to have different names (otherwise users will have a really hard time knowing which one is which).

[Poofjunior]

Ok, sounds good. Counter it is.

For the time when the message emits, is it critical that it falls on or near a particular whole number or multiple of a whole number?

[bruno-f-cruz]

Nah do it whenever it crosses the expected time and the board is "available" to work. I would say that some deviation from the requested frequency is expected. At 250hz, 5% would be a good target?

[Poofjunior]

Ok, coolies. Honestly, I expect it to be <1% deviation. Sending a USB transaction is the only "time-consuming" function device needs to execute. Nothing else blocks.

[Poofjunior]

All right; here's what I've got so far:

struct app_regs_t
{
    volatile uint16_t ConnectedDevices; // bitmask where each bit represents
                                         // whether a device is
                                         // connected (1) or disconnected (0)
                                         // to the corresponding clock output
                                         // channel.
    volatile uint32_t Counter;
    volatile uint16_t CounterFrequencyHz;
    volatile uint8_t AuxPortFn; // bit[0] = 1 --> slow uart
                                // bit[1] = 1 --> PPS
    // More app "registers" here.
};

We'll need to test these with Bonsai.

[bruno-f-cruz]

I am closing this issue as we already have the spec