Skip to content

Latest commit

 

History

History
116 lines (85 loc) · 3.69 KB

libflagship.md

File metadata and controls

116 lines (85 loc) · 3.69 KB
Raw

Ankermake M5 protocols

This repository tries to document and implement the various APIs associated with Ankermake M5 3D printers.

For now, MQTT and PPPP have reasonable coverage.

The protocol specifications themselves are written as Simple Type Format files.

Simple Type Format (.stf) files are lightly-structured, and can be used with project-specific template files, to generate any type of desired protocol-related output.

In this repository, we use the Transwarp compiler to compile the .stf files into python code files that implement the various protocols.

In the future, we might also generate C header files, reference documentation, etc, from the same .stf source files:

libflagship

A python library (libflagship) is provided in this repository, which implements the mqtt and pppp protocols used by Ankermake M5.

Let's take a look at demo-pppp.py, demonstrating basic usage of libflagship for working with PPPP data:

import libflagship.pppp as pppp
from rich import print

# binary message to parse
input = b'\xf1C\x00,EUPRAKM\x00\x00\x0009ABCDE\x00\x00\x00\x00\x02iz(\x1e\x14\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
print(f"input:   {input}")

# parsing a message into structured data
msg, tail = pppp.Message.parse(input)
print(f"decoded: {msg}")

# packing a structured message into binary output
output = msg.pack()
print(f"encoded: {output}")

# the output must match our original input
assert input == output

The expected output from running this script is:

input:   b'\xf1C\x00,EUPRAKM\x00\x00\x0009ABCDE\x00\x00\x00\x00\x02iz(\x1e\x14\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
decoded: PktP2pRdyAck(duid=Duid(prefix='EUPRAKM', serial=12345, check='ABCDE'), host=Host(afam=2, port=31337, addr='10.20.30.40'))
encoded: b'\xf1C\x00,EUPRAKM\x00\x00\x0009ABCDE\x00\x00\x00\x00\x02iz(\x1e\x14\n\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

First line shows the binary input data. The second line shows the structured data, which was parsed from the input data.

Finally, the last line demonstrates the serialized form of the structured data, demonstrating that the output is identical to the input.

Full PPPP packets can also be constructed entirely in python, like so:

# import all pppp names into top-level scope,
# to avoid having to prefix everything with `pppp.`
from libflagship.pppp import *

# construct message from python. notice how the syntax is identical
# to the printed output from the demo program above.
pkt = PktP2pRdyAck( \
    duid=Duid(prefix='EUPRAKM', serial=12345, check='ABCDE'), \
    host=Host(afam=2, port=31337, addr='10.20.30.40'))

# pack structured message back to binary data
data = pkt.pack()

Development

Some files in this library are auto-generated from the .stf sources and templates. These auto-generated files will have the following header:

## ------------------------------------------
## Generated by Transwarp
##
## THIS FILE IS AUTOMATICALLY GENERATED.
## DO NOT EDIT. ALL CHANGES WILL BE LOST.
## ------------------------------------------

To maintain these files, edit the template sources in templates/python/*.tpl instead:

# [first time only] install transwarp compiler tools
make install-tools

# edit input template
$EDITOR templates/python/pppp.tpl

# show diff between existing auto-generated file, and new result
make diff

# ...or, save new output
make update