Welcome to knittingpattern’s documentation!

Contents:

AYABInterface Installation Instructions

Package installation from Pypi

The AYABInterface library requires Python 3. It can be installed form the Python Package Index.

Windows

Install it with a specific python version under windows:

py -3 -m pip --no-cache-dir install --upgrade AYABInterface

Test the installed version:

py -3 -m pytest --pyargs AYABInterface

Linux

To install the version from the python package index, you can use your terminal and execute this under Linux:

sudo python3 -m pip --no-cache-dir install --upgrade AYABInterface

test the installed version:

python3 -m pytest --pyargs AYABInterface

Installation from Repository

You can setup the development version under Windows and Linux.

Linux

If you wish to get latest source version running, you can check out the repository and install it manually.

git clone https://github.com/fossasia/AYABInterface.git
cd AYABInterface
sudo python3 -m pip install --upgrade pip
sudo python3 -m pip install -r requirements.txt
sudo python3 -m pip install -r test-requirements.txt
py.test

To also make it importable for other libraries, you can link it into the site-packages folder this way:

sudo python3 setup.py link

Windows

Same as under Linux but you need to replace sudo python3 with py -3. This also counts for the following documentation.

Development Setup

Make sure that you have the repository installed.

Install Requirements

To install all requirements for the development setup, execute

pip install --upgrade -r requirements.txt -r test-requirements.txt -r dev-requirements.txt

Sphinx Documentation Setup

Sphinx was setup using the tutorial from readthedocs. It should be already setup if you completed the previous step.

Further reading:

With Notepad++ under Windows, you can run the make_html.bat file in the docs directory to create the documentation and show undocumented code.

Code Climate

To install the code climate command line interface (cli), read about it in their github repository You need docker to be installed. Under Linux you can execute this in the Terminal to install docker:

wget -qO- https://get.docker.com/ | sh
sudo usermod -aG docker $USER

Then, log in and out. Then, you can install the command line interface:

wget -qO- https://github.com/codeclimate/codeclimate/archive/master.tar.gz | tar xvz
cd codeclimate-* && sudo make install

Then, go to the AYABInterface repository and analyze it.

codeclimate analyze

Version Pinning

We use version pinning, described in this blog post (outdated). Also read the current version for how to set up.

After installation you can run

pip install -r requirements.in -r test-requirements.in -r dev-requirements.in
pip-compile --output-file requirements.txt requirements.in
pip-compile --output-file test-requirements.txt test-requirements.in
pip-compile --output-file dev-requirements.txt dev-requirements.in
pip-sync requirements.txt dev-requirements.txt test-requirements.txt
pip install --upgrade -r requirements.txt -r test-requirements.txt -r dev-requirements.txt

pip-sync uninstalls every package you do not need and writes the fix package versions to the requirements files.

Continuous Integration to Pypi

Before you put something on Pypi, ensure the following:

  1. The version is in the master branch on github.
  2. The tests run by travis-ci run successfully.

Pypi is automatically deployed by travis. See here. To upload new versions, tag them with git and push them.

setup.py tag_and_deploy

The tag shows up as a travis build. If the build succeeds, it is automatically deployed to Pypi.

Manual Upload to the Python Package Index

However, here you can see how to upload this package manually.

Version

Throughout this chapter, <new_version> refers to a a string of the form [0-9]+\.[0-9]+\.[0-9]+[ab]? or <MAYOR>.<MINOR>.<STEP>[<MATURITY>] where <MAYOR>, <MINOR> and, <STEP> represent numbers and <MATURITY> can be a letter to indicate how mature the release is.

  1. Create a new branch for the version.
git checkout -b <new_version>
  1. Increase the __version__ in __init__.py
    • no letter at the end means release
    • b in the end means Beta
    • a in the end means Alpha
  2. Commit and upload this version.
git add AYABInterface/__init__.py
git commit -m "version <new_version>"
git push origin <new_version>
  1. Create a pull-request.
  2. Wait for travis-ci to pass the tests.
  3. Merge the pull-request.
  4. Checkout the master branch and pull the changes from the commit.
git checkout master
git pull
  1. Tag the version at the master branch with a v in the beginning and push it to github.
git tag v<new_version>
git push origin v<new_version>
  1. Upload the code to Pypi.

Upload

First ensure all tests are running:

setup.py pep8

From docs.python.org:

setup.py sdist bdist_wininst upload register

Classifiers

You can find all Pypi classifiers here.

Reference

The AYABInterface Module Reference

AYABInterface Module

AYABInterface - a module to control the AYAB shield.

AYABInterface.NeedlePositions(*args, **kw)[source]

Create a new NeedlePositions object.

Returns:an AYABInterface.needle_positions.NeedlePositions
AYABInterface.get_machines()[source]

Return a list of all machines that can be used.

Return type:list
Returns:a list of Machines
AYABInterface.get_connections()[source]

Return a list of all available serial connections.

Return type:list
Returns:a list of AYABInterface.SerialPort. All of the returned objects have a connect() method and a name attribute.

actions Module

These are the actions that can be executed by the users.

class AYABInterface.actions.ActionMetaClass(name, bases, attributes)[source]

Bases: type

Metaclass for the actions.

This class makes sure each Action has tests.

If a class is named MyAction, each Action gets the method is_my_action() which returns False for all Actions expcept for MyAction it returns True.

__init__(name, bases, attributes)[source]

Create a new Action subclass.

class AYABInterface.actions.Action(*arguments)[source]

Bases: object

A base class for actions.

__eq__(other)[source]

Whether this object is equal to the other.

Return type:bool
__hash__()[source]

The hash of the object.

Return type:int
Returns:the hash() of the object
__init__(*arguments)[source]

Create a new Action.

Parameters:arguments (tuple) – The arguments passed to the action. These are also used to determine equality and the hash.
__repr__()[source]

Return this object as string.

Return type:str
__weakref__

list of weak references to the object (if defined)

is_action()

Test whether this is a Action.

Return type:bool
Returns:True
is_move_carriage_over_left_hall_sensor()

Test whether this is a MoveCarriageOverLeftHallSensor.

Return type:bool
Returns:False
is_move_carriage_to_the_left()

Test whether this is a MoveCarriageToTheLeft.

Return type:bool
Returns:False
is_move_carriage_to_the_right()

Test whether this is a MoveCarriageToTheRight.

Return type:bool
Returns:False
is_move_needles_into_position()

Test whether this is a MoveNeedlesIntoPosition.

Return type:bool
Returns:False
is_put_color_in_nut_a()

Test whether this is a PutColorInNutA.

Return type:bool
Returns:False
is_put_color_in_nut_b()

Test whether this is a PutColorInNutB.

Return type:bool
Returns:False
is_switch_carriage_to_mode_kc()

Test whether this is a SwitchCarriageToModeKc.

Return type:bool
Returns:False
is_switch_carriage_to_mode_nl()

Test whether this is a SwitchCarriageToModeNl.

Return type:bool
Returns:False
is_switch_off_machine()

Test whether this is a SwitchOffMachine.

Return type:bool
Returns:False
is_switch_on_machine()

Test whether this is a SwitchOnMachine.

Return type:bool
Returns:False
class AYABInterface.actions.SwitchCarriageToModeKc(*arguments)[source]

Bases: AYABInterface.actions.Action

The user switches the mode of the carriage to KC.

is_switch_carriage_to_mode_kc()

Test whether this is a SwitchCarriageToModeKc.

Return type:bool
Returns:True
class AYABInterface.actions.SwitchCarriageToModeNl(*arguments)[source]

Bases: AYABInterface.actions.Action

The user switches the mode of the carriage to NL.

is_switch_carriage_to_mode_nl()

Test whether this is a SwitchCarriageToModeNl.

Return type:bool
Returns:True
class AYABInterface.actions.MoveCarriageOverLeftHallSensor(*arguments)[source]

Bases: AYABInterface.actions.Action

The user moves the carriage over the left hall sensor.

is_move_carriage_over_left_hall_sensor()

Test whether this is a MoveCarriageOverLeftHallSensor.

Return type:bool
Returns:True
class AYABInterface.actions.MoveCarriageToTheLeft(*arguments)[source]

Bases: AYABInterface.actions.Action

The user moves the carriage to the left.

is_move_carriage_to_the_left()

Test whether this is a MoveCarriageToTheLeft.

Return type:bool
Returns:True
class AYABInterface.actions.MoveCarriageToTheRight(*arguments)[source]

Bases: AYABInterface.actions.Action

The user moves the carriage to the right.

is_move_carriage_to_the_right()

Test whether this is a MoveCarriageToTheRight.

Return type:bool
Returns:True
class AYABInterface.actions.PutColorInNutA(*arguments)[source]

Bases: AYABInterface.actions.Action

The user puts a color into nut A.

is_put_color_in_nut_a()

Test whether this is a PutColorInNutA.

Return type:bool
Returns:True
class AYABInterface.actions.PutColorInNutB(*arguments)[source]

Bases: AYABInterface.actions.Action

The user puts a color into nut B.

is_put_color_in_nut_b()

Test whether this is a PutColorInNutB.

Return type:bool
Returns:True
class AYABInterface.actions.MoveNeedlesIntoPosition(*arguments)[source]

Bases: AYABInterface.actions.Action

The user moves needles into position.

is_move_needles_into_position()

Test whether this is a MoveNeedlesIntoPosition.

Return type:bool
Returns:True
class AYABInterface.actions.SwitchOffMachine(*arguments)[source]

Bases: AYABInterface.actions.Action

The user switches off the machine.

is_switch_off_machine()

Test whether this is a SwitchOffMachine.

Return type:bool
Returns:True
class AYABInterface.actions.SwitchOnMachine(*arguments)[source]

Bases: AYABInterface.actions.Action

The user switches on the machine.

is_switch_on_machine()

Test whether this is a SwitchOnMachine.

Return type:bool
Returns:True

carriages Module

This module contains all the supported carriages.

class AYABInterface.carriages.Carriage[source]

Bases: object

A base class for carriages.

__eq__(other)[source]

Equivalent to self == other.

__hash__()[source]

Make this object hashable.

__repr__()[source]

This object as string.

__weakref__

list of weak references to the object (if defined)

class AYABInterface.carriages.KnitCarriage[source]

Bases: AYABInterface.carriages.Carriage

The carriage used for knitting.

interaction Module

This module can be used to interact with the AYAB Interface.

class AYABInterface.interaction.Interaction(knitting_pattern, machine)[source]

Bases: object

Interaction with the knitting pattern.

__init__(knitting_pattern, machine)[source]

Create a new interaction object.

Parameters:
__weakref__

list of weak references to the object (if defined)

actions

A list of actions to perform.

Returns:a list of AYABInterface.actions.Action
communicate_through(file)[source]

Setup communication through a file.

Return type:AYABInterface.communication.Communication
communication

The communication with the controller.

:rtype:AYABInterface.communication.Communication

machines Module

This module contains the information about the different types of machines.

Every machine specific knowledge should be put in this file. Machine specific knowledge is, for example:

  • the number of needles a machine supports
  • whether it is single or double bed
  • how many colors are supported
  • the name of the machine
class AYABInterface.machines.Machine[source]

Bases: object

The type of the machine.

This is an abstract base class and some methods need to be overwritten.

NAME = None

the name of the machine

__eq__(other)[source]

Equavalent of self == other.

Return type:bool
Returns:whether this object is equal to the other object
__hash__()[source]

Return the hash of this object.

See also

hash()

__repr__()[source]

Return this object as a string.

__weakref__

list of weak references to the object (if defined)

is_ck35()[source]

Whether this machine is a Brother CK-35.

Return type:bool
is_kh270()[source]

Whether this machine is a Brother KH-270.

Return type:bool
is_kh900()[source]

Whether this machine is a Brother KH-910.

Return type:bool
is_kh910()[source]

Whether this machine is a Brother KH-900.

Return type:bool
is_kh930()[source]

Whether this machine is a Brother KH-930.

Return type:bool
is_kh950()[source]

Whether this machine is a Brother KH-950.

Return type:bool
is_kh965()[source]

Whether this machine is a Brother KH-965.

Return type:bool
left_end_needle

The index of the leftmost needle.

Return type:int
Returns:0
name

The identifier of the machine.

needle_positions

The different needle positions.

Return type:tuple
needle_positions_to_bytes(needle_positions)[source]

Convert the needle positions to the wire format.

This conversion is used for The cnfLine Message.

Parameters:needle_positions – an iterable over needle_positions of length number_of_needles
Return type:bytes
number_of_needles

The number of needles of this machine.

Return type:int
right_end_needle

The index of the rightmost needle.

Return type:int
Returns:left_end_needle + number_of_needles - 1
class AYABInterface.machines.KH9XXSeries[source]

Bases: AYABInterface.machines.Machine

The base class for the KH9XX series.

needle_positions

The different needle positions.

Return type:tuple
Returns:the needle positions are “B” and “D”
number_of_needles

The number of needles on this machine.

Return type:int
Returns:200. The KH9XX series has 200 needles.
class AYABInterface.machines.CK35[source]

Bases: AYABInterface.machines.Machine

The machine type for the Brother CK-35.

needle_positions

The different needle positions.

Return type:tuple
Returns:the needle positions are “B” and “D”
number_of_needles

The number of needles on this machine.

Return type:int
Returns:200. The KH9XX series has 200 needles.
class AYABInterface.machines.KH900[source]

Bases: AYABInterface.machines.KH9XXSeries

The machine type for the Brother KH-900.

class AYABInterface.machines.KH910[source]

Bases: AYABInterface.machines.KH9XXSeries

The machine type for the Brother KH-910.

class AYABInterface.machines.KH930[source]

Bases: AYABInterface.machines.KH9XXSeries

The machine type for the Brother KH-930.

class AYABInterface.machines.KH950[source]

Bases: AYABInterface.machines.KH9XXSeries

The machine type for the Brother KH-950.

class AYABInterface.machines.KH965[source]

Bases: AYABInterface.machines.KH9XXSeries

The machine type for the Brother KH-965.

class AYABInterface.machines.KH270[source]

Bases: AYABInterface.machines.Machine

The machine type for the Brother KH-270.

needle_positions

The different needle positions.

Return type:tuple
Returns:the needle positions are “B” and “D”
number_of_needles

The number of needles on this machine.

Return type:int
Returns:200. The KH9XX series has 200 needles.
AYABInterface.machines.get_machines()[source]

Return a list of all machines.

Return type:list
Returns:a list of Machines

needle_positions Module

This module provides the interface to the AYAB shield.

class AYABInterface.needle_positions.NeedlePositions(rows, machine)[source]

Bases: object

An interface that just focusses on the needle positions.

__init__(rows, machine)[source]

Create a needle interface.

Parameters:
Raises:

ValueError – if the arguments are not valid, see check()

__weakref__

list of weak references to the object (if defined)

check()[source]

Check for validity.

Raises:ValueError
completed_row_indices

The indices of the completed rows.

Return type:list

When a row was completed, the index of the row turns up here. The order is preserved, entries may occur duplicated.

get_row(index, default=None)[source]

Return the row at the given index or the default value.

machine

The machine these positions are on.

on_row_completed(callable)[source]

Add an observer for completed rows.

Parameters:callable – a callable that is called with the row index as first argument

When row_completed() was called, this callable is called with the row index as first argument. Call this method several times to register more observers.

row_completed(index)[source]

Mark the row at index as completed.

This method notifies the obsevrers from on_row_completed().

serial Module

The serial interface.

Execute this module to print all serial ports currently available.

AYABInterface.serial.list_serial_port_strings()[source]

Lists serial port names.

Raises:EnvironmentError – On unsupported or unknown platforms
Returns:A list of the serial ports available on the system
AYABInterface.serial.list_serial_ports()[source]

Return a list of all available serial ports.

Return type:list
Returns:a list of serial ports
class AYABInterface.serial.SerialPort(port)[source]

Bases: object

A class abstracting the port behavior.

__init__(port)[source]

Create a new serial port instance.

Parameters:port (str) – the port to connect to

Note

The baud rate is specified in Serial Communication

__repr__()[source]

Return this object as string.

Return type:str
__weakref__

list of weak references to the object (if defined)

connect()[source]

Return a connection to this port.

Return type:serial.Serial
name

The name of the port for displaying.

Return type:str

utils Module

Utility methods.

AYABInterface.utils.sum_all(iterable, start)[source]

Sum up an iterable starting with a start value.

In contrast to sum(), this also works on other types like lists and sets.

AYABInterface.utils.number_of_colors(rows)[source]

Determine the numer of colors in the rows.

Return type:int
AYABInterface.utils.next_line(last_line, next_line_8bit)[source]

Compute the next line based on the last line and a 8bit next line.

The behaviour of the function is specified in The reqLine Message.

Parameters:
  • last_line (int) – the last line that was processed
  • next_line_8bit (int) – the lower 8 bits of the next line
Returns:

the next line closest to last_line

AYABInterface.utils.camel_case_to_under_score(camel_case_name)[source]

Return the underscore name of a camel case name.

Parameters:camel_case_name (str) – a name in camel case such as "ACamelCaseName"
Returns:the name using underscores, e.g. "a_camel_case_name"
Return type:str

The AYABInterface.convert Module Reference

convert Module

Conversion of colors to needle positions.

AYABInterface.convert.colors_to_needle_positions(rows)[source]

Convert rows to needle positions.

Returns:
Return type:list
class AYABInterface.convert.NeedlePositions(needle_coloring, colors, two_colors)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

static __new__(_cls, needle_coloring, colors, two_colors)

Create new instance of NeedlePositions(needle_coloring, colors, two_colors)

__repr__()

Return a nicely formatted representation string

colors

Alias for field number 1

needle_coloring

Alias for field number 0

two_colors

Alias for field number 2

The AYABInterface.communication Module Reference

communication Module

This module is used to communicate with the shield.

Requirement: Make objects from binary stuff.

class AYABInterface.communication.Communication(file, get_needle_positions, machine, on_message_received=(), left_end_needle=None, right_end_needle=None)[source]

Bases: object

This class comunicates with the AYAB shield.

__init__(file, get_needle_positions, machine, on_message_received=(), left_end_needle=None, right_end_needle=None)[source]

Create a new Communication object.

Parameters:
  • file – a file-like object with read and write methods for the communication with the Arduino. This could be a serial.Serial or a socket.socket.makefile().
  • get_needle_positions – a callable that takes an index and returns None or an iterable over needle positions.
  • machine (AYABInterface.machines.Machine) – the machine to use for knitting
  • on_message_received (list) – an iterable over callables that takes a received message whenever it comes in. Since state changes only take place when a message is received, this can be used as an state observer.
  • left_end_needle – A needle number on the machine. Other needles that are on the left side of this needle are not used for knitting. Their needle positions are not be set.
  • right_end_needle – A needle number on the machine. Other needles that are on the right side of this needle are not used for knitting. Their needle positions are not be set.
__weakref__

list of weak references to the object (if defined)

api_version_is_supported(api_version)[source]

Return whether an api version is supported by this class.

Return type:bool
Returns:if the api version is supported
Parameters:api_version (int) – the api version

Currently supported api versions: 4

can_receive_messages()[source]

Whether tihs communication is ready to receive messages.]

Return type:bool
assert not communication.can_receive_messages()
communication.start()
assert communication.can_receive_messages()
communication.stop()
assert not communication.can_receive_messages()
controller

Information about the controller.

If no information about the controller is received, the return value is None.

If information about the controller is known after The cnfInfo Message was received, you can access these values:

>>> communication.controller.firmware_version
(5, 2)
>>> communication.controller.firmware_version.major
5
>>> communication.controller.firmware_version.minor
2
>>> communication.controller.api_version
4
last_requested_line_number

The number of the last line that was requested.

Return type:int
Returns:the last requested line number or 0
left_end_needle

The left end needle of the needle positions.

Return type:int
Returns:the left end needle of the machine
lock

The lock of the communication.

In case you parallelize() the communication, you may want to use this lock to make shure the parallelization does not break your code.

needle_positions

A cache for the needle positions.

Return type:AYABInterface.communication.cache.NeedlePositionCache
on_message(callable)[source]

Add an observer to received messages.

Parameters:callable – a callable that is called every time a AYABInterface.communication.host_messages.Message is sent or a AYABInterface.communication.controller_messages.Message is received
parallelize(seconds_to_wait=2)[source]

Start a parallel thread for receiving messages.

If start() was no called before, start will be called in the thread. The thread calls receive_message() until the state is_connection_closed().

Parameters:seconds_to_wait (float) – A time in seconds to wait with the parallel execution. This is useful to allow the controller time to initialize.
receive_message()[source]

Receive a message from the file.

right_end_needle

The left end needle of the needle positions.

Return type:int
Returns:the right end needle of the machine
runs_in_parallel()[source]

Whether the communication runs in parallel.

Return type:bool
Returns:whether parallelize() was called and the communication still receives messages and is not stopped
send(host_message_class, *args)[source]

Send a host message.

Parameters:
  • host_message_class (type) – a subclass of AYABImterface.communication.host_messages.Message
  • args – additional arguments that shall be passed to the host_message_class as arguments
start()[source]

Start the communication about a content.

Parameters:content (Content) – the content of the communication.
state

The state this object is in.

Returns:the state this communication object is in.
Return type:AYABInterface.communication.states.State

Note

When calling parallelize() the state can change while you check it.

stop()[source]

Stop the communication with the shield.

cache Module

Convert and cache needle positions.

class AYABInterface.communication.cache.NeedlePositionCache(get_needle_positions, machine)[source]

Bases: object

Convert and cache needle positions.

__init__(get_needle_positions, machine)[source]

Create a new NeedlePositions object.

__weakref__

list of weak references to the object (if defined)

get(line_number)[source]

Return the needle positions or None.

Parameters:line_number (int) – the number of the line
Return type:list
Returns:the needle positions for a specific line specified by line_number or None if no were given
get_bytes(line_number)[source]

Get the bytes representing needle positions or None.

Parameters:line_number (int) – the line number to take the bytes from
Return type:bytes
Returns:the bytes that represent the message or None if no data is there for the line.

Depending on the machine, the length and result may vary.

get_line_configuration_message(line_number)[source]

Return the cnfLine content without id for the line.

Parameters:line_number (int) – the number of the line
Return type:bytes
Returns:a cnfLine message without id as defined in The cnfLine Message
is_last(line_number)[source]

Whether the line number is has no further lines.

Return type:bool
Returns:is the next line above the line number are not specified

carriages Module

This module contains the carriages which are communicated by the firmware.

class AYABInterface.communication.carriages.NullCarriage(needle_position)[source]

Bases: AYABInterface.communication.carriages.Carriage

This is an empty carriage.

class AYABInterface.communication.carriages.KnitCarriage(needle_position)[source]

Bases: AYABInterface.communication.carriages.Carriage

The carriage for knitting.

is_knit_carriage()[source]

This is a knit carriage.

Return type:bool
Returns:True
class AYABInterface.communication.carriages.HoleCarriage(needle_position)[source]

Bases: AYABInterface.communication.carriages.Carriage

The carriage for creating holes.

is_hole_carriage()[source]

This is a knit carriage.

Return type:bool
Returns:True
class AYABInterface.communication.carriages.UnknownCarriage(needle_position)[source]

Bases: AYABInterface.communication.carriages.Carriage

The carriage type if the type is not known.

is_unknown_carriage()[source]

The type of this carriage is unknown.

Return type:bool
Returns:True
AYABInterface.communication.carriages.id_to_carriage_type(carriage_id)[source]

Return the carriage type for an id.

Return type:type
Returns:a subclass of Carriage
class AYABInterface.communication.carriages.Carriage(needle_position)[source]

Bases: object

A base class for carriages.

__init__(needle_position)[source]

Create a new carriage.

Parameters:needle_position (int) – the position of the carriage
__weakref__

list of weak references to the object (if defined)

is_hole_carriage()[source]

Whether this is a hole carriage.

Return type:bool
Returns:False
is_knit_carriage()[source]

Whether this is a knit carriage.

Return type:bool
Returns:False
is_unknown_carriage()[source]

Whether the type of this carriage is unkown.

Return type:bool
Returns:False
needle_position

The needle position of the carriages.

Returns:the needle position of the carriage counted from the left, starting with 0
Return type:int

hardware_messages Module

This modue contains all the messages taht are received.

AYABInterface.communication.hardware_messages.read_message_type(file)[source]

Read the message type from a file.

class AYABInterface.communication.hardware_messages.StateIndication(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.FixedSizeMessage

This message shows the state of the controller.

MESSAGE_ID = 132

The first byte that indicates this message

carriage

The carriage which is reported.

Return type:AYABInterface.communication.carriages.Carriage
Returns:the carriage with information about its position
current_needle

The current needle position.

Return type:int
is_ready_to_knit()[source]

Whether this message indicates that the controller can knit now.

is_state_indication()[source]

Whether this is a InformationConfirmation message.

Return type:bool
Returns:True
is_valid()[source]

Whether this messages matches the specification.

left_hall_sensor_value

The value of the left hall sensor.

Return type:int
received_by(visitor)[source]

Call visitor.receive_state_indication.

right_hall_sensor_value

The value of the left hall sensor.

Return type:int
class AYABInterface.communication.hardware_messages.LineRequest(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.FixedSizeMessage

The controller requests a line.

MESSAGE_ID = 130

The first byte that indicates this message

is_line_request()[source]

Whether this is a LineRequest message.

Return type:bool
Returns:True
line_number

The line number that was requested.

received_by(visitor)[source]

Call visitor.receive_line_request.

class AYABInterface.communication.hardware_messages.TestConfirmation(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.SuccessConfirmation

This message is sent at/when

MESSAGE_ID = 196

The first byte that indicates this message

is_test_confirmation()[source]

Whether this is a TestConfirmation message.

Return type:bool
Returns:True
received_by(visitor)[source]

Call visitor.test_information_confirmation.

class AYABInterface.communication.hardware_messages.InformationConfirmation(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.FixedSizeMessage

This message is the answer in the initial handshake.

A InformationRequest requests this message from the controller to start the initial handshake.

MESSAGE_ID = 195

The first byte that indicates this message

api_version

The API version of the controller.

Return type:int
api_version_is_supported()[source]

Whether the communication object supports this API version.

Return type:bool
firmware_version

The firmware version of the controller.

Return type:FirmwareVersion
minor_version = int()
mayor_version = int()

assert message.firmware_version == (mayor_version, minor_version)
assert message.firmware_version.major == mayor_version
assert message.firmware_version.minor == minor_version
is_information_confirmation()[source]

Whether this is a InformationConfirmation message.

Return type:bool
Returns:True
received_by(visitor)[source]

Call visitor.receive_information_confirmation.

class AYABInterface.communication.hardware_messages.Debug(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.Message

This message contains debug output from the controller.

bytes

The debug message as bytes.

Return type:bytes
Returns:the debug message as bytes without the b'\r\n' at the end
is_debug()[source]

Whether this is a Debug message.

Return type:bool
Returns:False
received_by(visitor)[source]

Call visitor.receive_debug.

class AYABInterface.communication.hardware_messages.StartConfirmation(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.SuccessConfirmation

This marks the success or failure of a reqStart message.

MESSAGE_ID = 193

The first byte that indicates this message

is_start_confirmation()[source]

Whether this is a StartConfirmation message.

Return type:bool
Returns:True
received_by(visitor)[source]

Call visitor.receive_state_confirmation.

class AYABInterface.communication.hardware_messages.SuccessConfirmation(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.FixedSizeMessage

Base class for massages of success and failure.

is_success()[source]

Whether the configuration was successful.

Return type:bool
is_valid()[source]

Whether this message is valid.

class AYABInterface.communication.hardware_messages.UnknownMessage(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.FixedSizeMessage

This is a special message for unknown message types.

is_unknown()[source]

Whether this is a StateIndication message.

Return type:bool
Returns:True
is_valid()[source]

Whether the message is valid.

Return type:bool
Returns:False
received_by(visitor)[source]

Call visitor.receive_unkown.

class AYABInterface.communication.hardware_messages.Message(file, communication)[source]

Bases: object

This is the base class for messages that are received.

__init__(file, communication)[source]

Create a new Message.

__repr__()[source]

This object as string.

Return type:str
__weakref__

list of weak references to the object (if defined)

is_connection_closed()[source]

Whether this is a ConnectionClosed message.

Return type:bool
Returns:False
is_debug()[source]

Whether this is a Debug message.

Return type:bool
Returns:False
is_from_controller()[source]

Whether this message is sent by the controller.

Return type:bool
Returns:True
is_from_host()[source]

Whether this message is sent by the host.

Return type:bool
Returns:False
is_information_confirmation()[source]

Whether this is a InformationConfirmation message.

Return type:bool
Returns:False
is_line_request()[source]

Whether this is a LineRequest message.

Return type:bool
Returns:False
is_start_confirmation()[source]

Whether this is a StartConfirmation message.

Return type:bool
Returns:False
is_state_indication()[source]

Whether this is a StateIndication message.

Return type:bool
Returns:False
is_test_confirmation()[source]

Whether this is a TestConfirmation message.

Return type:bool
Returns:False
is_unknown()[source]

Whether this is a StateIndication message.

Return type:bool
Returns:False
is_valid()[source]

Whether the message is valid.

Return type:bool
Returns:True
wants_to_answer()[source]

Whether this message produces and answer message.

Return type:bool
Returns:False
class AYABInterface.communication.hardware_messages.ConnectionClosed(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.Message

This message is notified about when the connection is closed.

is_connection_closed()[source]

Whether this is a ConnectionClosed message.

Return type:bool
Returns:True
received_by(visitor)[source]

Call visitor.receive_connection_closed.

class AYABInterface.communication.hardware_messages.FirmwareVersion(major, minor)

Bases: tuple

__getnewargs__()

Return self as a plain tuple. Used by copy and pickle.

__getstate__()

Exclude the OrderedDict from pickling

static __new__(_cls, major, minor)

Create new instance of FirmwareVersion(major, minor)

__repr__()

Return a nicely formatted representation string

major

Alias for field number 0

minor

Alias for field number 1

class AYABInterface.communication.hardware_messages.FixedSizeMessage(file, communication)[source]

Bases: AYABInterface.communication.hardware_messages.Message

This is a message of fixed size.

__init__(file, communication)[source]

Create a new Message.

read_end_of_message()[source]

Read the b”rn” at the end of the message.

host_messages Module

This module contains the messages that are sent to the controller.

class AYABInterface.communication.host_messages.Message(file, communication, *args, **kw)[source]

Bases: object

This is the interface for sent messages.

MESSAGE_ID = None

the first byte to identify this message

__init__(file, communication, *args, **kw)[source]

Create a new Request object

__repr__()[source]

This message as string inclding the bytes.

Return type:str
__weakref__

list of weak references to the object (if defined)

as_bytes()[source]

The message represented as bytes.

Return type:bytes
content_bytes()[source]

The message content as bytes.

Return type:bytes
init()[source]

Override this method.

is_from_controller()[source]

Whether this message is sent by the controller.

Return type:bool
Returns:False
is_from_host()[source]

Whether this message is sent by the host.

Return type:bool
Returns:True
send()[source]

Send this message to the controller.

class AYABInterface.communication.host_messages.StartRequest(file, communication, *args, **kw)[source]

Bases: AYABInterface.communication.host_messages.Message

This is the start of the conversation.

MESSAGE_ID = 1

the first byte to identify this message

content_bytes()[source]

Return the start and stop needle.

Return type:bytes
init(left_end_needle, right_end_needle)[source]

Initialize the StartRequest with start and stop needle.

Raises:
left_end_needle

The needle to start knitting with.

Return type:int
Returns:value where 0 <= value <= 198
right_end_needle

The needle to start knitting with.

Return type:int
Returns:value where 1 <= value <= 199
class AYABInterface.communication.host_messages.LineConfirmation(file, communication, *args, **kw)[source]

Bases: AYABInterface.communication.host_messages.Message

This message send the data to configure a line.

MESSAGE_ID = 66

the first byte to identify this message

content_bytes()[source]

Return the start and stop needle.

init(line_number)[source]

Initialize the StartRequest with the line number.

class AYABInterface.communication.host_messages.InformationRequest(file, communication, *args, **kw)[source]

Bases: AYABInterface.communication.host_messages.Message

Start the initial handshake.

MESSAGE_ID = 3

the first byte to identify this message

class AYABInterface.communication.host_messages.TestRequest(file, communication, *args, **kw)[source]

Bases: AYABInterface.communication.host_messages.Message

Start the test mode of the controller.

MESSAGE_ID = 4

the first byte to identify this message

states Module

This module contains the state machine for the communication class.

Click on this image to go to the states from the diagram:

State Disgram for the Communication class.
class AYABInterface.communication.states.State(communication)[source]

Bases: object

The base class for states.

__init__(communication)[source]

Create a new state.

Please use the subclasses of this.

Parameters:communication (AYABInterface.communication.Communication) – the communication object which is in this state
__repr__()[source]

This object as string.

Return type:str
__weakref__

list of weak references to the object (if defined)

communication_started()[source]

Call when the communication starts.

enter()[source]

Called when the state is entered.

The AYABInterface.communication.Communication.state is set to this state.

exit()[source]

Called when this state is left.

The AYABInterface.communication.Communication.state is set to this state.

is_before_knitting()[source]

Whether the knitting should start soon.

Return type:bool
Returns:False
is_connection_closed()[source]

Whether the connection is closed.

Return type:bool
Returns:False
is_final()[source]

Whether the communication is over.

Return type:bool
Returns:False
is_initial_handshake()[source]

Whether the communication object is in the intial handshake.

Return type:bool
Returns:False
is_initializing_machine()[source]

Whether the machine is currently being initialized.

Return type:bool
Returns:False
is_knitting()[source]

Whether the machine ready to knit or knitting.

Return type:bool
Returns:False
is_knitting_line()[source]

Whether the machine knits a line.

Return type:bool
Returns:False
is_knitting_started()[source]

Whether the machine ready to knit the first line.

Return type:bool
Returns:false
is_starting_to_knit()[source]

Whether the machine initialized and knitting starts.

Return type:bool
Returns:False
is_unsupported_api_version()[source]

Whether the API version of communcation and controller do not match.

Return type:bool
Returns:False
is_waiting_for_start()[source]

Whether this state is waiting for the start.

Return type:bool
Returns:False
is_waiting_for_the_communication_to_start()[source]

Whether the communication can be started.

When this is True, you call call AYABInterface.communication.Communication.start() to leave the state.

Return type:bool
Returns:False
receive_connection_closed(message)[source]

Receive a ConnectionClosed message.

Parameters:message – a ConnectionClosed message

If the is called, the communication object transits into the ConnectionClosed.

receive_debug(message)[source]

Receive a Debug message.

Parameters:message – a Debug message

This logs the debug message.

receive_information_confirmation(message)[source]

Receive a InformationConfirmation message.

Parameters:message – a InformationConfirmation message
receive_line_request(message)[source]

Receive a LineRequest message.

Parameters:message – a LineRequest message
receive_message(message)[source]

Receive a message from the controller.

Parameters:message (AYABInterface.communication.hardware_messages.Message) – the message to receive

This method calls message.received_by which dispatches the call to the receive_* methods.

receive_start_confirmation(message)[source]

Receive a StartConfirmation message.

Parameters:message – a StartConfirmation message
receive_state_indication(message)[source]

Receive a StateIndication message.

Parameters:message – a StateIndication message
receive_test_confirmation(message)[source]

Receive a TestConfirmation message.

Parameters:message – a TestConfirmation message
receive_unknown(message)[source]

Receive a UnknownMessage message.

Parameters:message – a UnknownMessage message
class AYABInterface.communication.states.ConnectionClosed(communication)[source]

Bases: AYABInterface.communication.states.FinalState

The connection is closed.

is_connection_closed()[source]

The connection is closed.

Return type:bool
Returns:True
class AYABInterface.communication.states.WaitingForStart(communication)[source]

Bases: AYABInterface.communication.states.State

Waiting for the start() method to be called.

This is the initial state of a AYABInterface.communication.Communication.

communication_started()[source]

Call when the communication starts.

The communication object transits into InitialHandshake.

is_before_knitting()[source]

Whether the knitting should start soon.

Return type:bool
Returns:True
is_waiting_for_start()[source]

Whether this state is waiting for the start.

Call AYABInterface.communication.Comunication.start() to leave this state.

Return type:bool
Returns:True
class AYABInterface.communication.states.InitialHandshake(communication)[source]

Bases: AYABInterface.communication.states.State

The communication has started.

enter()[source]

This starts the handshake.

A AYABInterface.communication.host_messages.InformationRequest is sent to the controller.

is_before_knitting()[source]

Whether the knitting should start soon.

Return type:bool
Returns:True
is_initial_handshake()[source]

Whether the communication object is in the intial handshake.

Return type:bool
Returns:True
receive_information_confirmation(message)[source]

A InformationConfirmation is received.

If the api version is supported, the communication object transitions into a InitializingMachine, if unsupported, into a UnsupportedApiVersion

class AYABInterface.communication.states.UnsupportedApiVersion(communication)[source]

Bases: AYABInterface.communication.states.FinalState

The api version of the controller is not supported.

is_unsupported_api_version()[source]

Whether the API version of communcation and controller do not match.

Return type:bool
Returns:True
class AYABInterface.communication.states.InitializingMachine(communication)[source]

Bases: AYABInterface.communication.states.State

The machine is currently being intialized.

is_before_knitting()[source]

Whether the knitting should start soon.

Return type:bool
Returns:True
is_initializing_machine()[source]

Whether the machine is currently being initialized.

Return type:bool
Returns:True
is_waiting_for_carriage_to_pass_the_left_turn_mark()[source]

The carriage should be moved over the left turn mark.

Return type:bool
Returns:True
receive_state_indication(message)[source]

Receive a StateIndication message.

Parameters:message – a StateIndication message

If the message says that the controller is is ready to knit, there is a transition to StartingToKnit or else the messages are ignored because they come from The reqTest Message.

class AYABInterface.communication.states.StartingToKnit(communication)[source]

Bases: AYABInterface.communication.states.State

The cnfStart Message is sent and we wait for an answer.

enter()[source]

Send a StartRequest.

is_before_knitting()[source]

The knitting should start soon.

Return type:bool
Returns:True
is_starting_to_knit()[source]

The machine initialized and knitting starts.

Return type:bool
Returns:True
receive_start_confirmation(message)[source]

Receive a StartConfirmation message.

Parameters:message – a StartConfirmation message

If the message indicates success, the communication object transitions into KnittingStarted or else, into StartingFailed.

class AYABInterface.communication.states.StartingFailed(communication)[source]

Bases: AYABInterface.communication.states.FinalState

The starting process has failed.

is_starting_failed()[source]

The machine machine could not be configured to start.

Return type:bool
Returns:True
class AYABInterface.communication.states.KnittingStarted(communication)[source]

Bases: AYABInterface.communication.states.State

The knitting started and we are ready to receive The reqLine Message.

is_knitting()[source]

The machine ready to knit or knitting.

Return type:bool
Returns:True
is_knitting_started()[source]

The machine ready to knit the first line.

Return type:bool
Returns:True
receive_line_request(message)[source]

Receive a LineRequest message.

Parameters:message – a LineRequest message

The communicaion transisitions into a KnittingLine.

class AYABInterface.communication.states.KnittingLine(communication, line_number)[source]

Bases: AYABInterface.communication.states.State

The machine is currently knitting a line.

__init__(communication, line_number)[source]

The machine is knitting a line.

enter()[source]

Send a LineConfirmation to the controller.

When this state is entered, a AYABInterface.communication.host_messages.LineConfirmation is sent to the controller. Also, the last line requested is set.

is_knitting()[source]

The machine ready to knit or knitting.

Return type:bool
Returns:True
is_knitting_last_line()[source]

Whether the line currently knit is the last line.

Return type:bool
is_knitting_line()[source]

The machine knits a line.

Return type:bool
Returns:True
line_number

The number if the line which is currently knit.

Return type:int
receive_line_request(message)[source]

Receive a LineRequest message.

Parameters:message – a LineRequest message

The communicaion transisitions into a KnittingLine.

class AYABInterface.communication.states.FinalState(communication)[source]

Bases: AYABInterface.communication.states.State

Base class for states that can not reach knitting.

is_final()[source]

From the current state, the knitting can not be reached.

Return type:bool
Returns:True

Communication Specification

This document specifies the communication between the host and a controller with the AYAB firmware.

Serial Communication

115200 baud

Line Ending: \n\r (10 13) Each message ends with a Line Ending.

Sequence Chart

sequence diagram for the communication between host and controller

The host waits for a indState(true) message before requesting to start the knitting. On startup, the Arduino continuously checks for the initialization of the machine (carriage passed left hall sensor). When this happens, it sends an indState(true) to tell the host that the machine is ready to knit. After receiving this message, the host sends a reqStart message, which is immediately confirmed with a cnfStart message. When reqStart was successful, the Arduino begins to poll the host for line data with reqLine, the host answers with cnfLine. This reqLine/cnfLine happens each time the carriage moves passed the borders given by the Start/StopNeedle parameters in reqStart. When the host does not have any more lines to send, it marks the last line with the lastLine flag in its last cnfLine message.

To see an example implementation, see the states of the communication module.

Message Identifier Format

Messages start with a byte that identifies their type. This byte is called “id” or “message id” in the following document. This table lists all the bits of this byte and assigns their purpose:

Bit Value Name Description and Values
7 128 message source
  • 0 = the message is from the host
  • 1 = the message is from the controller
6 64 message type
  • 0 = the message is a request
  • 1 = the message is a confirmation of a request
5 32 reserved must be zero
4 16
3 8 message identifier

These are the values that identify the message.

2 4
1 2
0 1

Message definitions (API v4)

The length is the total length with id and parameters. Note that the two characters \r\n following the message are not included in the length.

source name id length parameters
host

reqStart

0x01 3

0xaa 0xbb

  • aa = left end needle (Range: 0..198)
  • bb = right end needle (Range: 1..199)

Start and

hardware

cnfStart

0xC1 2

0x0a

  • a = success (0 = false, 1 = true)
hardware

reqLine

0x82 2

0xaa

  • aa = line number (Range: 0..255)
host

cnfLine

0x42 29

0xaa 0xbb[24, 23, 22, ... 1, 0] 0xcc 0xdd

  • aa = line number (Range: 0..255)
  • bb[24 to 0] = binary pixel data
  • cc = flags (bit 0: lastLine)
  • dd = CRC8 Checksum
host

reqInfo

0x03 1  
hardware

cnfInfo

0xC3 4

0xaa 0xbb 0xcc

  • aa = API Version Identifier
  • bb = Firmware Major Version
  • cc = Firmware Minor Version
hardware

indState

0x84 8

0x0a 0xBB 0xbb 0xCC 0xcc 0xdd 0xee

  • a = ready (0 = false, 1 = true)
  • BBbb = int left hall sensor value
  • CCcc = int right hall sensor value
  • dd = the carriage
    • 0 = no carriage detected
    • 1 = knit carriage “Strickschlitten”
    • 2 = hole carriage “Lochmusterschlitten”
  • ee = the needle number currently in progress
hardware

debug

0x23 var A debug string. The id is the character #. The length is variable and can be determined by the end \r\n'.
host

reqTest

0x04 1 put the controller into test mode
host

cnfTest

0xC4 2

0x0a

  • a = success (0 = false, 1 = true)

The reqStart Message

The host starts the knitting process.

The cnfStart Message

The controller indicates the success of The reqStart Message.

The reqLine Message

The controller requests a new line from the host.

More than 256 lines are supported. There are three possibilities for the next line based on the last line:

  1. the new line is greater than the last line
  2. the new line is lower than the last line
  3. the new line is the last line

We choose the line closest to the last line. This is trivial for (3). In case two lines are equally distant from the last line, we choose the smaller line.

This is computed by the function AYABInterface.utils.next_line() which is tested and can be seen as a reference implementation for other languages.

The cnfLine Message

The host answers The reqLine Message with a line configuration.

This table shows the message content without the first byte that identifies the message:

Byte Name Description
0 line number These are the lowest 8 bit of the line. They must match the line number in The reqLine Message.
1 needle positions

Each bit of the bytes represents a needle position.

  • 0 = “B”
  • 1 = “D”

For the exact mapping of bits to needles see the table below.

2
...
24
25
26 flags

Bits: 0000000L

  • L - “LastLine” (0 = false, 1 = true)
27 crc8 checksum This checksum is computed from bytes 0 to 26, including byte 26. The controller may use this checksum to check the result and if the checksum does not match, it can send The reqLine Message anew.

In the following table, you can see the mapping of bytes to needles.

Note

  • The Needles are counted from the leftmost needle on the machine.
  • The Needle count starts with 0.
  • The Byte numbering is taken from the table above.
  • The Bit numbering is consistent with Message Identifier Format. The highest bit has the number 7 and the lowest bit has number 0.
Byte 1 2   24 25
Bit 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 ... 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
Needle 0 1 2 3 4 5 6 7 8 9 ... 198 199

The reqInfo Message

The host initializes the handshake.

The cnfInfo Message

The controller answers The reqInfo Message with the API version.

The indState Message

This is sent when the controller indicates its state. When ready it is

The debug Message

This message ends with a \r\n like evey message. It contains debug information from the controller.

The reqTest Message

This message puts the controller in a test mode instead of a knitting mode.

The cnfTest Message

This messsage confirms whether the controller is in the test mode. If success is indicated, the controller sends The indState Message messages periodically, containing the sensor and position values.

References

See also

Indices and tables