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
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:
- The version is in the master branch on github.
- 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.
- Create a new branch for the version.
git checkout -b <new_version>
- Increase the
__version__
in __init__.py- no letter at the end means release
b
in the end means Betaa
in the end means Alpha
- Commit and upload this version.
git add AYABInterface/__init__.py
git commit -m "version <new_version>"
git push origin <new_version>
- Create a pull-request.
- Wait for travis-ci to pass the tests.
- Merge the pull-request.
- Checkout the master branch and pull the changes from the commit.
git checkout master
git pull
- 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>
- 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
Reference¶
The AYABInterface
Module Reference¶
AYABInterface
Module¶
AYABInterface - a module to control the AYAB shield.
See also
-
AYABInterface.
NeedlePositions
(*args, **kw)[source]¶ Create a new NeedlePositions object.
Returns: an AYABInterface.needle_positions.NeedlePositions
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
, eachAction
gets the methodis_my_action()
which returnsFalse
for allActions
expcept forMyAction
it returnsTrue
.
-
class
AYABInterface.actions.
Action
(*arguments)[source]¶ Bases:
object
A base class for actions.
-
__init__
(*arguments)[source]¶ Create a new
Action
.Parameters: arguments (tuple) – The arguments passed to the action. These are also used to determine equality
and thehash
.
-
__weakref__
¶ list of weak references to the object (if defined)
-
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_switch_carriage_to_mode_kc
()¶ Test whether this is a SwitchCarriageToModeKc.
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.
-
class
AYABInterface.actions.
SwitchCarriageToModeNl
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user switches the mode of the carriage to NL.
-
class
AYABInterface.actions.
MoveCarriageOverLeftHallSensor
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user moves the carriage over the left hall sensor.
-
class
AYABInterface.actions.
MoveCarriageToTheLeft
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user moves the carriage to the left.
-
class
AYABInterface.actions.
MoveCarriageToTheRight
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user moves the carriage to the right.
-
class
AYABInterface.actions.
PutColorInNutA
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user puts a color into nut A.
-
class
AYABInterface.actions.
PutColorInNutB
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user puts a color into nut B.
-
class
AYABInterface.actions.
MoveNeedlesIntoPosition
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user moves needles into position.
-
class
AYABInterface.actions.
SwitchOffMachine
(*arguments)[source]¶ Bases:
AYABInterface.actions.Action
The user switches off the machine.
carriages
Module¶
This module contains all the supported carriages.
-
class
AYABInterface.carriages.
Carriage
[source]¶ Bases:
object
A base class for carriages.
-
__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: - knitting_pattern – a
KnittingPattern
- machine (AYABInterface.machines.Machine) – the machine to knit on
- knitting_pattern – a
-
__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
-
__weakref__
¶ list of weak references to the object (if defined)
-
name
¶ The identifier of the machine.
-
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 lengthnumber_of_needles
Return type: bytes
-
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.
-
class
AYABInterface.machines.
CK35
[source]¶ Bases:
AYABInterface.machines.Machine
The machine type for the Brother CK-35.
-
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
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: - rows (list) – a list of lists of
needle positions
- Machine – the machine type to use
Raises: ValueError – if the arguments are not valid, see
check()
- rows (list) – a list of lists of
-
__weakref__
¶ list of weak references to the object (if defined)
-
check
()[source]¶ Check for validity.
Raises: ValueError – - if not all lines are as long as the
number of needles
- if the contents of the rows are not
needle positions
- if not all lines are as long as the
-
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.
-
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, thiscallable
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.
See also
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 See also
-
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
-
__weakref__
¶ list of weak references to the object (if defined)
-
connect
()[source]¶ Return a connection to this port.
Return type: serial.Serial
-
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 likelists
andsets
.
-
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: Returns: the next line closest to
last_line
See also
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 asocket.socket.makefile()
. - get_needle_positions – a callable that takes an
index
and returnsNone
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. Sincestate
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.
- file – a file-like object with read and write methods for the
communication with the Arduino. This could be a
-
__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 supportedParameters: 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 thislock
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 aAYABInterface.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 callsreceive_message()
until thestate
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. See also
-
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
- host_message_class (type) – a subclass of
-
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.
-
cache
Module¶
Convert and cache needle positions.
-
class
AYABInterface.communication.cache.
NeedlePositionCache
(get_needle_positions, machine)[source]¶ Bases:
object
Convert and cache needle positions.
-
__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
orNone
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
-
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.
-
class
AYABInterface.communication.carriages.
HoleCarriage
(needle_position)[source]¶ Bases:
AYABInterface.communication.carriages.Carriage
The carriage for creating holes.
-
class
AYABInterface.communication.carriages.
UnknownCarriage
(needle_position)[source]¶ Bases:
AYABInterface.communication.carriages.Carriage
The carriage type if the type is not known.
-
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)
-
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.
See also
-
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
-
-
class
AYABInterface.communication.hardware_messages.
LineRequest
(file, communication)[source]¶ Bases:
AYABInterface.communication.hardware_messages.FixedSizeMessage
The controller requests a line.
See also
-
MESSAGE_ID
= 130¶ The first byte that indicates this message
-
line_number
¶ The line number that was requested.
-
-
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
-
-
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.See also
-
MESSAGE_ID
= 195¶ The first byte that indicates this message
-
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
-
-
class
AYABInterface.communication.hardware_messages.
Debug
(file, communication)[source]¶ Bases:
AYABInterface.communication.hardware_messages.Message
This message contains debug output from the controller.
See also
-
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.
See also
-
MESSAGE_ID
= 193¶ The first byte that indicates this message
-
-
class
AYABInterface.communication.hardware_messages.
SuccessConfirmation
(file, communication)[source]¶ Bases:
AYABInterface.communication.hardware_messages.FixedSizeMessage
Base class for massages of success and failure.
-
class
AYABInterface.communication.hardware_messages.
UnknownMessage
(file, communication)[source]¶ Bases:
AYABInterface.communication.hardware_messages.FixedSizeMessage
This is a special message for unknown message types.
-
class
AYABInterface.communication.hardware_messages.
Message
(file, communication)[source]¶ Bases:
object
This is the base class for messages that are received.
-
__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_from_controller
()[source]¶ Whether this message is sent by the controller.
Return type: bool Returns: True
-
is_information_confirmation
()[source]¶ Whether this is a InformationConfirmation 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
-
-
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.
-
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.
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
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
AYABInterface.communication.host_messages.
StartRequest
(file, communication, *args, **kw)[source]¶ Bases:
AYABInterface.communication.host_messages.Message
This is the start of the conversation.
See also
-
MESSAGE_ID
= 1¶ the first byte to identify this message
-
init
(left_end_needle, right_end_needle)[source]¶ Initialize the StartRequest with start and stop needle.
Raises: - TypeError – if the arguments are not integers
- ValueError – if the values do not match the specification
-
-
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.
See also
-
MESSAGE_ID
= 66¶ the first byte to identify this message
-
-
class
AYABInterface.communication.host_messages.
InformationRequest
(file, communication, *args, **kw)[source]¶ Bases:
AYABInterface.communication.host_messages.Message
Start the initial handshake.
See also
-
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.
See also
-
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:
-
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
-
__weakref__
¶ list of weak references to the object (if defined)
-
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_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_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 callAYABInterface.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
messageIf the is called, the communication object transits into the
ConnectionClosed
.
-
receive_debug
(message)[source]¶ Receive a Debug message.
Parameters: message – a Debug
messageThis 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 thereceive_*
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.
-
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
.
-
-
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_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 aInitializingMachine
, if unsupported, into aUnsupportedApiVersion
-
-
class
AYABInterface.communication.states.
UnsupportedApiVersion
(communication)[source]¶ Bases:
AYABInterface.communication.states.FinalState
The api version of the controller is not supported.
-
class
AYABInterface.communication.states.
InitializingMachine
(communication)[source]¶ Bases:
AYABInterface.communication.states.State
The machine is currently being intialized.
-
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
messageIf the message says that the controller is
is ready to knit
, there is a transition toStartingToKnit
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.
-
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
messageIf the message indicates success, the communication object transitions into
KnittingStarted
or else, intoStartingFailed
.
-
-
class
AYABInterface.communication.states.
StartingFailed
(communication)[source]¶ Bases:
AYABInterface.communication.states.FinalState
The starting process has failed.
-
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_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
messageThe 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.
-
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, thelast line requested
is set.
-
receive_line_request
(message)[source]¶ Receive a LineRequest message.
Parameters: message – a LineRequest
messageThe communicaion transisitions into a
KnittingLine
.
-
Communication Specification¶
This document specifies the communication between the host and a controller with the AYAB firmware.
Sequence Chart¶
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 |
|
6 | 64 | message type |
|
5 | 32 | reserved | must be zero |
4 | 16 | ||
3 | 8 | message identifier | These are the values that identify the message. See also |
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 | 0x01 | 3 |
Start and |
|
hardware | 0xC1 | 2 |
|
|
hardware | 0x82 | 2 |
|
|
host | 0x42 | 29 |
|
|
host | 0x03 | 1 | ||
hardware | 0xC3 | 4 |
|
|
hardware | 0x84 | 8 |
|
|
hardware | 0x23 | var | A debug string. The id is the character # .
The length is variable and can be determined
by the end \r\n' . |
|
host | 0x04 | 1 | put the controller into test mode | |
host | 0xC4 | 2 |
|
The reqStart
Message¶
The host starts the knitting process.
- Python:
StartRequest
- Arduino: h_reqStart
- table: reqStart
- requests answer: The cnfStart Message
- direction: host → controller
The cnfStart
Message¶
The controller indicates the success of The reqStart Message.
- Python:
StartConfirmation
- Arduino: h_reqStart
- table: reqStart
- answers: The reqStart Message
- direction: controller → host
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:
- the new line is greater than the last line
- the new line is lower than the last line
- 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.
- Python:
LineRequest
- Arduino: Knitter::reqLine
- table: reqLine
- requests answer: The cnfLine Message
- direction: controller → host
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.
For the exact mapping of bits to needles see the table below. |
2 | ||
... | ||
24 | ||
25 | ||
26 | flags | Bits:
|
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 |
- Python:
LineConfirmation
- Arduino: h_cnfLine
- table: cnfLine
- answers: The reqLine Message
- direction: host → controller
The reqInfo
Message¶
The host initializes the handshake.
- Python:
InformationRequest
- Arduino: h_reqInfo
- table: reqInfo
- requests answer: The reqInfo Message
- direction: host → controller
The cnfInfo
Message¶
The controller answers The reqInfo Message with the API version.
- Python:
InformationConfirmation
- Arduino: h_reqInfo
- table: cnfInfo
- answers: The reqInfo Message
- direction: controller → host
The indState
Message¶
This is sent when the controller indicates its state.
When ready
it is
1
, then this is the first state indication. The machine is now ready to knit0
, the controller is in test mode. This message is sent periodically. The reqTest Message switches this on.- Python:
StateIndication
- Arduino: Knitter::indState
- table: indState
- direction: controller → host
The debug
Message¶
This message ends with a \r\n
like evey message.
It contains debug information from the controller.
- Python:
Debug
- Arduino: DEBUG_PRINT
- table: debug
- direction: controller → host
The reqTest
Message¶
This message puts the controller in a test mode instead of a knitting mode.
- Python:
TestRequest
- Arduino: h_reqTest
- table: reqTest
- requests answer: The cnfTest Message
- direction: host → controller
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.
- Python:
TestConfirmation
- Arduino: h_reqTest
- table: cnfTest
- answers: The reqTest Message
- direction: controller → host
References¶
See also
- the original specification
- the
hardware messages module
for messages sent by the hardware - the
host messages module
for messages sent by the host - a discussion about the specification