The MIN protocol specification and reference implementation

min-protocol, updated 🕥 2022-12-30 12:35:54

Microcontroller Interconnect Network protocol version 2.0

This MIN repository includes the specification, a standard C API and reference implementations for C and Python. See the Wiki for further details:

http://github.com/min-protocol/min/wiki

File structure:

target/                 Embedded code
    min.c               MIN code designed to run on an embedded system (from 8-bit MCUs upwards)
    min.h               Header file that defines the API to min
    sketch_example1     Arduino sketch for an example program
host/                   Python code to run on a host PC
    min.py              MIN 2.0 reference implementation with support for MIN via Pyserial
    listen.py           Example program to run on a host and talk to an Arduino board

There is also a Rust implementation of MIN for both host and target:

https://github.com/qianchenzhumeng/min-rs

All software and documentation available under the terms of the MIT License:

The MIT License (MIT)

Copyright (c) 2014-2017 JK Energy Ltd.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Issues

Received spurious ACK

opened on 2022-12-03 14:34:49 by milo1000

Scenario for this problem: 1. Host (using min.py) sends some frames to client (which is Arduino with min.c) 2. Arduino listens for incoming frames and sends "keep alive" frames to notify host that everything is OK 3. At that point Arduino client is restarted (hard-reset) 4. Host keeps sending ACK frames for some old seq, client prints "Received spurious ACK" and basically stops working 5. Due to lack of "keep alive" frames, Host decides to perform transport_reset() - that resets client, but unfortunately Host keeps sending "spurious ACK" To fix that I've added self._rn = 0 to _transport_fifo_reset, it seems to work OK, but need to be confirmed by someone with expertise. def _transport_fifo_reset(self): self._transport_fifo = [] self._last_received_anything_ms = self._now_ms() self._last_sent_ack_time_ms = self._now_ms() self._last_sent_frame_ms = 0 self._last_received_frame_ms = 0 self._sn_min = 0 self._sn_max = 0 self._rn = 0

Review Comments

opened on 2022-08-15 13:42:11 by GuptaGagan111

Hi, In function valid_frame_received(), transport_fifo_send() is called without checking if the Tx has space or not. Probably if(ON_WIRE_SIZE(frame->payload_len) <= min_tx_space(self->port)) should also be called before calling the line transport_fifo_send during nacked message tranmission. see the below code snipshot.

            // Now retransmit the number of frames that were requested
            for(i = 0; i < num_nacked; i++) {
                struct transport_frame *retransmit_frame = &self->transport_fifo.frames[idx];
                transport_fifo_send(self, retransmit_frame);
                idx++;
                idx &= TRANSPORT_FIFO_SIZE_FRAMES_MASK;
            }

STM32Cube USB VCP

opened on 2022-05-19 17:03:42 by Tyrn

Hi,

Is there any experience with MIN protocol outside Arduino? I'm having trouble adapting it to the middleware supplied by STM32CubeIDE. Shouldn't be too difficult; unfortunately, I'm a newbie.

Sorry, I did some Google research, didn't find anything.

Ability to calculate CRC in HW

opened on 2021-07-12 20:59:17 by oswinrodrigues

The two MCUs I am working with - and most modern processors today, I believe - have built-in CRC computation units / modules / engines. As such, I'm curious if there is the possibility to feed in my own CRC, rather that MIN computing on its end?

I understand that the design intent is to be HW-agnostic. Perhaps some hook defined where the application can, on its end, invoke the CRC driver and return accordingly?

To be clear, more than requesting this be added to the library, I'm inquiring if it is possible in the current state and, if not, how easy it would be to do this in a fork of my own?

Support up to 32kB of payload using 2-byte length

opened on 2021-06-08 10:40:26 by bojanpotocnik None

Question regarding the signal layer json

opened on 2021-03-30 11:21:56 by Fladdan

Hi @kentindell

I'm currently having a project, where I want to use your nice min protocol! I have an PC which is communicating over UART with an uC and that uC is communicating with another uC over RS485. I'm using a windows PC and STM32 m4 and m7 controllers.

The example from this repo is already working between STM32 and the PC.

My question: Would it be possible for you to upload an example of the implementation on the Arduino & python side with the signal layer in the json format? Like the example you posted in your blog: https://kentindell.wordpress.com/2015/02/18/micrcontroller-interconnect-network-min-version-1-0/.

It would be nice to get an working example of how to implement the generated .c and .h files from the python code generator you wrote.

Best regards and thank you for the work you have done on this open source project, Daniel

min-protocol
GitHub Repository