CAN Kingdom is a higher-layer protocol based on CAN. This library provides a hardware-agnostic implementation of the CAN Kingdom library. Contains implementations of the mayor, the king and the data structures, as well as an interface for creating a postmaster implementation, which is hardware dependent.
CAN Kingdom building blocks.
Bit: a bit.
Line: A line is 8 bits, a byte.
Envelope: a CAN ID (or rather, the arbitration field)
Page: 0-8 lines (a CAN data field, i.e. maximum 8 bytes).
Letter: A page in an envelope (a CAN frame).
Form: Explains the contents of a a page, line by line. It also specified whether the city produces this information or requires it. Forms are numbered using a list number and a form number. One list can contain up to 255 forms, and one city can have up to 255 lists. The forms should be specified in a city’s documentation.
The mayor can use the form to encode and decode data. For two cities to exchange data, their forms must match exactly. Thus, the mayor can choose to either specify multiple forms with the same information to fit different systems, or he can give the king the possibility to compose forms from predefined line lists.
Forms do not need to be implemented in code, only in documentation.
Document: a set of pages that should be carried in the same envelope. The documents should be specified in a city’s documentation. A document may be composed of one or multiple pages. For such documents, every page should have one line (or at least some bits) that specify the page number, since all the data is sent in one envelope. The envelope number is not specified in a document, but in a folder (see below).
New documents can be constructed by the king if the mayor provides predefined bit, line or page lists. The mayor must also allocate space for any new documents, either beforehand or dynamically.
Lists: Provided by mayors to list the documents, forms, lines and bits the city provides or requires. The king can use these lists to design their own documents according to the system’s needs, or use the primitives provided as-is. Lists are identified using direction (Transmit or Receive) and number, i.e. T0, T1, etc. or R0, R1, etc.
Folder: structure for how a document should be used in a kingdom. A city may provide many documents, however the kingdom founder (system designer) might only need some of them. Then for every document the founder wants to use, they create a folder to hold it. The folders are what makes it possible to go from document to a set of CAN frames.
Each folder is labeled. The label contains the folder number, document list number, the document number, whether to transmit or receive said document, the CAN control field, the RTR bit of the CAN message, whether to enable the folder or not, the envelopes assigned to it, and which of these envelopes should be enabled or disabled. A folder may be allocated more than one envelope. A folder may be empty or contain at most one document.
Folders 0 and 1 are reserved by CAN Kingdom for the King’s document and the Mayor’s document, respectively.
Record: a record is a collective name for an item in a list, i.e. a document in a document list is called a record and a form in a form list is a record, etc. A record is identified using the same notation as lists, with the added record number. For instance, record number 1 in list T0 is denoted T0.1.
It should be noted that not all parts of the building blocks should be implemented in code. Some of the information should reside in the documentation of the cities. In the document for example, it is important that the document designer provides the list and document number, in order for the system designer to be able to differentiate between various documents in code, however the description for how to interpret the pages in the document should be provided in the documentation.
Defines
The max value for the CAN DLC. Corresponds to 8 bytes.
The max value for a CAN ID when using standard (11-bit) identifiers.
The max value for a CAN ID when using extended (29-bit) identifiers.
For extracting IDs out of King’s pages.
The highest possible 40-bit EAN number.
Default number of the king’s folder.
Default number of the mayor’s folder.
The default letter’s CAN ID.
For use with king’s page 1 when requesting a mayor’s response.
Max number of lines per page.
Max number of envelopes that can be assigned to a folder.
Max number of pages in a document.
Max number of records in a list.
Enums
Error codes.
Values:
OK.
Invalid CAN ID.
Invalid CAN DLC.
Invalid ck_can_bit_timing_t.
Invalid King’s letter.
Unsupported King’s page.
Some parameters are not compatible.
User tried to set a reserved folder number.
Invalid ck_action_mode_t.
Invalid ck_comm_mode_t.
Invalid ck_list_type_t.
Missing input argument to function.
List, folder, document or page is full.
Item not found in list or folder.
Library has not been initialized yet.
Failed to send a letter.
Returned when setting a mode fails.
Error code from boolean return type functions.
Failed to access some peripheral.
Input argument to function is wrong in some way.
Supported king’s pages.
Values:
King’s page 0.
King’s page 1.
King’s page 2.
King’s page 8.
King’s page 16.
King’s page 17.
Action mode as defined by the CAN Kingdom specification.
Values:
Keep the current mode.
Start the city.
Stop the city.
Reset the city.
Communication mode as defined by the CAN Kingdom specification.
Values:
Keep the current mode.
Set the CAN controller in silent mode.
Set the CAN controller in listen-only mode.
Enable CAN communication.
Communication mode flags, used in KP0.
Values:
Reset communication by going through the startup sequence with new bit timing settings.
Skip listening for a good message during startup sequence.
Don’t skip listening for a good message during startup sequence.
Skip 200ms wait for default letter during startup sequence.
Don’t 200ms wait for default letter during startup sequence.
Only CK_CITY_MODE_KEEP_CURRENT is defined, the rest is defined by the user.
Values:
Keep the current mode.
Direction enum.
Values:
Receive direction.
Transmit direction.
Some list types for storing predefined data in a city, which can be used by the king to construct new pages or documents.
Values:
Bit list.
Line list.
Page list.
Document list.
Defines envelope actions for use with KP2.
Values:
Assign envelope to folder.
Expel envelope from previous assignment.
Envelope must be disabled in the same message for this to work.
Move envelope to new folder.
Defines document actions for use with KP16.
Values:
Remove document from folder.
Insert document into folder.
A folder contains at most one document. Inserting a document into a folder with a document already in it will replace the old document with the new one.
Functions
Check if the specified action mode is a valid action mode.
mode – ck_action_mode_t to check.
CK_ERR_INVALID_ACTION_MODE if mode is invalid.
CK_OK on success.
Check if the specified communication mode is a valid communication mode.
mode – ck_comm_mode_t to check.
CK_ERR_INVALID_COMM_MODE if mode is invalid.
CK_OK on success.
Check if the specified list type is valid.
type – ck_list_type_t to check.
CK_ERR_INVALID_LIST_TYPE if type is invalid.
CK_OK on success.
Check if the given ck_can_bit_timing_t is valid.
The checking performed by the function relate to the CAN standard for what is allowed and what is not allowed. Some hardware may be able to set some values that this function will reject. In that case, the user will have to perform validation themselves.
bit_timing – pointer to parameters to check.
CK_ERR_INVALID_CAN_BIT_TIMING if bit_timing is invalid.
CK_OK on success.
Returns a CAN Kingdom default letter.
The default letter is a letter with CAN ID 2031 and 8 lines each containing 0xAA
.
the created letter.
Returns bit timing parameters specifying a bit rate of 125 Kbit/s and a sampling point of 87.5%.
the ck_can_bit_timing_t.
Page structure, represents the data in a CAN frame.
Envelope structure, represents the header of a CAN frame.
Letter structure, for creating CAN messages from folders.
The document structure contains a list of pages that should be sent using the same envelope.
If a document contains more than one page, the pages should have a pagination number in order to detect errors during transmission, such as omission of pages or duplicates transmission.
Public Members
Direction of the document.
How many pages the document contains.
The folder structure links a document to a set of envelopes.
It contains information that can be set by both the king and the mayor. Describes how to send or receive a document. In practice, it is used to assign CAN IDs to various messages and control whether or not they should be sent.
Public Members
Folder number.
Document list number.
Document number.
Direction of the folder.
CAN DLC.
CAN RTR bit.
Folder enabled / disabled.
How many envelopes have been assigned.
Assigned envelopes.
The specification allows more than one envelope to be assigned to a folder.
A generic structure for storing line lists, page flists or document lists.
The type of the records parameter depends on the value of the type parameter.
list_type value |
record value |
---|---|
uint8_t * |
|
uint8_t * |
|
The uint8_t *
in a #CK_BIT_LIST will be treated as a contiguous bit array. This means the record count should reflect the number of bits, not the number of bytes in the list.
Public Members
The type of items this list contains.
List number. Must be unique for each direction and type.
Number of records in the list.
List of pointers to records.
Defines the CAN bit timing parameters needed to set the postoffice settings.
The value of Phase segment 1 + propagation segment will be inferred from the following equation: time_quanta = 1 + prop_seg + phase_seg1 + phase_seg2
, where 8 <= time_quanta <= 25
and 2 <= phase_seg2 <= 8
.
Public Members
Defines the clock prescaler, which will determine the bit rate.
It’s important to know the clock frequency of the CAN peripheral to set the correct bit rate.
1 <= prescaler <= 32
Number of time quanta.
Phase segment 2.
Synchronization jump width, 1 <= sjw <= 4
. Must also be less than the minimum of phase_seg1 and phase_seg2.
Functions to set up a mayor in a CAN Kingdom system.
The idea is that the user will define some parameters for their mayor as specified by the ck_mayor_t struct, then the library will initialize its state from these parameters when the user calls ck_mayor_init(). Then, ck_process_kings_letter() can be used to act on commands from the king. The postmaster implementation is responsible for parsing CAN messages and converting them to letters, then the user needs to call ck_process_kings_letter() to process the letter if it’s a king’s letter.
Defines
Limited to 6 groups for ease of implementation.
Can be redefined during compilation if wanted.
Functions
Sets the parameters needed to utilize the mayor library.
This function must be called before any other functions in this library can be used.
This function does a number of things:
It verifies that the user is setting up the mayor with the required parameters.
It sets up the internal state of the mayor library.
It defines the mayor’s document which is needed to communicate in a CAN Kingdom system.
It sets up the folders for the king’s document and the mayor’s document.
mayor – parameters for setting up the mayor.
CK_ERR_MISSING_PARAMETER if some required parameter is not set.
CK_ERR_INVALID_PARAMETER if some parameter is set incorrectly.
CK_ERR_ITEM_NOT_FOUND if missing a requred list.
CK_ERR_CAPACITY_REACHED if a requred list is too small.
CK_OK on success.
Parse the king’s letter and act on it.
Not all return codes are listed, since some of the errors may be user defined.
letter – the received king’s letter.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_INVALID_KINGS_LETTER if the letter is not a valid king’s letter.
CK_ERR_UNSUPPORTED_KINGS_PAGE if the letter contains a king’s page not supported by this implementation.
CK_ERR_CAPACITY_REACHED if the king tries to assign more envelopes than possible.
CK_ERR_INVALID_CAN_ID received CAN ID is out of bounds.
CK_ERR_INVALID_FOLDER_NUMBER reserved folder number was received.
CK_ERR_ITEM_NOT_FOUND folder, record or mayor’s page not found.
CK_ERR_SEND_FAILED failed to send mayor’s page.
CK_ERR_INVALID_LIST_TYPE if an accessed list doesn’t have a valid type.
CK_ERR_INVALID_PARAMETER some parameters on the king’s page are invalid, or the passed letter is NULL.
CK_OK on success or if the letter is not addressed to the caller.
Adds a user-defined mayor’s page to the mayor’s document.
The function will store a pointer to the page instead of copying it. Therefore, the page needs to persist in memory.
page – the page to add to the mayor’s document.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_INVALID_PARAMETER if page is NULL.
CK_ERR_CAPACITY_REACHED if the mayor’s document cannot hold more pages.
CK_OK on success.
Send the document in the specified folder.
Will look for the given folder, check if it’s a transmit folder and enabled, then send the document within it. For each enabled envelope in the folder, the document will be sent using that envelope, and for each page in the document a separate letter will be sent. Take for example a folder with 2 envelopes assigned to it and enabled (0xA and 0xB), and whose document has 2 pages. Then, the letters will be sent in the following order:
Letter with envelope 0xA, page 0
Letter with envelope 0xA, page 1
Letter with envelope 0xB, page 0
Letter with envelope 0xB, page 1
folder_no – the requested folder number.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_ITEM_NOT_FOUND if the folder or it’s document don’t exist.
CK_ERR_SEND_FAILED if sending a letter fails.
CK_OK on success or if document is not sent due to being a receive document or in a receive folder.
Sends the specified mayor’s page.
page_no – mayor’s page number.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_ITEM_NOT_FOUND if the page doesn’t exist.
CK_ERR_SEND_FAILED if sending the letter fails.
CK_OK on success or if mayor’s folder is disabled for some reason.
Checks if the envelope is assigned to the king’s folder.
envelope – envelope to check.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_FALSE if it’s not assigned.
CK_OK if it’s assigned.
Tries to find the folder that the given envelope is assigned to.
envelope – envelope to check.
folder – to which the envelope is assigned, if found.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_FALSE if the envelope is not assigned to any folder.
CK_OK if it’s assigned.
Set the communication mode.
mode – the desired communication mode.
ck_apply_comm_mode() return codes.
Return the currently set communication mode.
Returned value is not valid if mayor is not initialized.
Returns the current base number.
Returned value is not valid if mayor is not initialized.
Sets the base number.
base_no – the base number to set.
has_extended_id – whether the base number should use extended CAN IDs.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_INVALID_CAN_ID if the base number is not a valid CAN ID.
CK_OK on success.
Checks if the given letter is the default letter.
letter – the letter to check.
CK_ERR_FALSE if it’s not the default letter.
CK_OK if it is.
Function that should be called when the default letter is received.
The city should always call this function when a default letter is received, in order for the mayor library to update its state accordingly.
ck_set_comm_mode() return codes.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_OK on success.
Function that should be called when waiting for a default letter times out.
The CAN Kingdom startup sequence specifies that a city should wait at most 200ms for a default letter. Once this timeout is reached, the city should call this function to update the mayor’s state.
ck_set_comm_mode() return codes.
ck_load_bit_timing() return codes.
ck_set_bit_timing() return codes.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_OK on success.
Function that should be called when a CAN message is correctly received.
Notifies the mayor library that a correct letter has been received and that the currently set bit timing parameters are compatible with the current system.
ck_send_mayors_page() return codes.
ck_save_bit_timing() return codes.
CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.
CK_ERR_SET_MODE_FAILED if failed setting the communication mode.
CK_OK on success.
Struct contains pointers to parameters that should be defined by the user.
The parameters are used by the mayor library to initialize the library state.
Public Members
40-bit EAN-13 number.
40-bit serial number.
The city address. Must not be 0. Can be changed by the king.
The group addresses.
Can be changed by the king. The city always belongs to group 0 as well.
Function for setting the action mode.
Should return CK_OK on success.
Function for setting the city mode.
City modes are defined by the mayor. Should return CK_OK on success.
Function for starting a 200ms one-shot timer.
When the timer finishes, ck_default_letter_timeout() should be called. This should be handled by the user application.
Number of folders the mayor has.
Must be at least 2 for the king’s and mayor’s folders, which are initialized by ck_mayor_init().
Pointer to user-allocated folders.
Folder numbers 0 and 1 are reserved by CAN Kingdom for the king’s document and the mayor’s document, respectively.
Number of lists this mayor has.
Must be at least 2, since we need at least one transmit document list and one receive document list.
Pointer to all the mayor’s lists, such as document lists, page lists, and line lists.
The mandatory lists are the transmit document list and the receive document list. Record no 0 in the transmit document list and the receive document list is reserved by CAN Kingdom and will be set up by ck_mayor_init().
This file defines the structures and functions needed to implement a capital city.
Provides the mandatory king’s pages 0-2 and the optional king’s pages 16 and 17.
Functions
KP0 terminates the setup phase.
Orders a mayor to set his city into a specific working mode, e.g., in a “Run” or “Freeze” mode.
args – ck_kp0_args_t value with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INVALID_ACTION_MODE if the given action mode is invalid.
CK_ERR_INVALID_COMM_MODE if the given comm mode is invalid.
CK_OK on success.
KP1 is the initiating page.
It provides the base number and asks for mayor’s response.
args – ck_kp1_args_t value with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.
CK_OK on success.
KP2 is used to assign, expel or transfer envelopes from/to folders.
args – ck_kp2_args_t value with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INCOMPATIBLE_PARAMS if some of the args are incompatible.
CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.
CK_OK on success.
KP8 is used to set the CAN bit timing settings for a city.
address – city or group address.
args – ck_can_bit_timing_t with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INCOMPATIBLE_PARAMS if some of the args are incompatible.
CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.
CK_OK on success.
KP16 Sets the folder label and/or places a document into a folder.
args – ck_kp16_args_t value with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INVALID_FOLDER_NUMBER if a reserved folder number is given.
CK_ERR_INVALID_CAN_DLC if the given DLC value is out of bounds.
CK_OK on success.
KP17 Creates a document, a page or a line from predefined page, line, or bit lists.
args – ck_kp17_args_t value with the desired values.
page – will be populated with the created king’s page.
CK_ERR_INVALID_LIST_TYPE if the given list type is invalid.
CK_OK on success.
Struct defining parameters for king’s page 0.
Public Members
City or group address.
Action mode.
Communication mode.
Communication mode flags to set.
City mode.
Only CK_CITY_MODE_KEEP_CURRENT is predefined. Modes are defined by mayor and specified in their city’s documentation.
Struct defining parameters for king’s page 1.
Public Members
City or group address.
The mayor’s response page in the mayor’s document.
Defined by the mayor and should be specified in the documentation. If no response is required, use CK_KP1_NO_RESPONSE_REQUESTED.
Base number of kingdom. This should be defined by the king.
Whether to use standard or extended CAN IDs.
Struct defining parameters for king’s page 2.
Compressed envelopes are not implemented.
Public Members
City or group address.
Envelope argument.
Folder number.
Envelope action to take.
Struct defining parameters for king’s page 16.
Public Members
City or group address.
Folder number.
at most CK_CAN_MAX_DLC.
The rtr bit.
Direction of the target document.
Document action to take.
Enable use of the folder.
Document list number.
Document number in list.
Struct defining parameters for king’s page 17.
We use the term “record” to denote an item in a list.
Public Members
City or group address.
Direction of the source and target records.
Target list type.
Source list number.
Source record number.
Target list number.
Target record number.
Where to put the specified record in the target, i.e.
a form number in a document, a line number on a page, or a bit number on a line.