user-icon
profile
contact us

applications

Software

The Rover’s boards come with some reference applications that can be used to construct a basic radio controlled car. The basic Rover layout consists of two servo boards, one to control the steering servo and one to control the ESC, and one IO board to interface with the radio receiver. This requires two applications, the Servo application and the SBUS Receiver application. Both applications make use of the CAN Kingdom library.

Servo

This reference application takes CAN messages and converts them into PWM output. It also measures the servo voltage and the servo current draw, then reports them over CAN.

SBUS Receiver

The SBUS Receiver reference application allows for controlling the Rover using conventional radio controllers from the hobby market. It reads a radio receiver’s SBUS output using an analog port configured for UART communication, then converts the received data to CAN messages containing steering, throttle and trim signals.

CAN Kingdom

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.

types.h

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

CK_CAN_MAX_DLC

The max value for the CAN DLC. Corresponds to 8 bytes.

CK_CAN_MAX_STD_ID

The max value for a CAN ID when using standard (11-bit) identifiers.

CK_CAN_MAX_EXT_ID

The max value for a CAN ID when using extended (29-bit) identifiers.

CK_CAN_ID_MASK

For extracting IDs out of King’s pages.

CK_MAX_EAN_NO

The highest possible 40-bit EAN number.

CK_KINGS_FOLDER_NO

Default number of the king’s folder.

CK_MAYORS_FOLDER_NO

Default number of the mayor’s folder.

CK_DEFAULT_LETTER_ENVELOPE

The default letter’s CAN ID.

CK_NO_RESPONSE_REQUESTED

For use with king’s page 1 when requesting a mayor’s response.

CK_MAX_LINES_PER_PAGE

Max number of lines per page.

CK_MAX_ENVELOPES_PER_FOLDER

Max number of envelopes that can be assigned to a folder.

CK_MAX_PAGES_PER_DOCUMENT

Max number of pages in a document.

CK_MAX_RECORDS_PER_LIST

Max number of records in a list.

Enums

enum ck_err_t

Error codes.

Values:

enumerator CK_OK

OK.

enumerator CK_ERR_INVALID_CAN_ID

Invalid CAN ID.

enumerator CK_ERR_INVALID_CAN_DLC

Invalid CAN DLC.

enumerator CK_ERR_INVALID_CAN_BIT_TIMING

Invalid ck_can_bit_timing_t.

enumerator CK_ERR_INVALID_KINGS_LETTER

Invalid King’s letter.

enumerator CK_ERR_UNSUPPORTED_KINGS_PAGE

Unsupported King’s page.

enumerator CK_ERR_INCOMPATIBLE_PARAMS

Some parameters are not compatible.

enumerator CK_ERR_INVALID_FOLDER_NUMBER

User tried to set a reserved folder number.

enumerator CK_ERR_INVALID_ACTION_MODE

Invalid ck_action_mode_t.

enumerator CK_ERR_INVALID_COMM_MODE

Invalid ck_comm_mode_t.

enumerator CK_ERR_INVALID_LIST_TYPE

Invalid ck_list_type_t.

enumerator CK_ERR_MISSING_PARAMETER

Missing input argument to function.

enumerator CK_ERR_CAPACITY_REACHED

List, folder, document or page is full.

enumerator CK_ERR_ITEM_NOT_FOUND

Item not found in list or folder.

enumerator CK_ERR_NOT_INITIALIZED

Library has not been initialized yet.

enumerator CK_ERR_SEND_FAILED

Failed to send a letter.

enumerator CK_ERR_SET_MODE_FAILED

Returned when setting a mode fails.

enumerator CK_ERR_FALSE

Error code from boolean return type functions.

enumerator CK_ERR_PERIPHERAL

Failed to access some peripheral.

enumerator CK_ERR_INVALID_PARAMETER

Input argument to function is wrong in some way.

enum ck_kings_page_t

Supported king’s pages.

Values:

enumerator CK_KP0

King’s page 0.

enumerator CK_KP1

King’s page 1.

enumerator CK_KP2

King’s page 2.

enumerator CK_KP8

King’s page 8.

enumerator CK_KP16

King’s page 16.

enumerator CK_KP17

King’s page 17.

enum ck_action_mode_t

Action mode as defined by the CAN Kingdom specification.

Values:

enumerator CK_ACTION_MODE_KEEP_CURRENT

Keep the current mode.

enumerator CK_ACTION_MODE_RUN

Start the city.

enumerator CK_ACTION_MODE_FREEZE

Stop the city.

enumerator CK_ACTION_MODE_RESET

Reset the city.

enum ck_comm_mode_t

Communication mode as defined by the CAN Kingdom specification.

Values:

enumerator CK_COMM_MODE_KEEP_CURRENT

Keep the current mode.

enumerator CK_COMM_MODE_SILENT

Set the CAN controller in silent mode.

enumerator CK_COMM_MODE_LISTEN_ONLY

Set the CAN controller in listen-only mode.

enumerator CK_COMM_MODE_COMMUNICATE

Enable CAN communication.

enum ck_comm_flags_t

Communication mode flags, used in KP0.

Values:

enumerator CK_COMM_RESET

Reset communication by going through the startup sequence with new bit timing settings.

enumerator CK_COMM_SKIP_LISTEN

Skip listening for a good message during startup sequence.

enumerator CK_COMM_DONT_SKIP_LISTEN

Don’t skip listening for a good message during startup sequence.

enumerator CK_COMM_SKIP_WAIT

Skip 200ms wait for default letter during startup sequence.

enumerator CK_COMM_DONT_SKIP_WAIT

Don’t 200ms wait for default letter during startup sequence.

enum ck_city_mode_t

Only CK_CITY_MODE_KEEP_CURRENT is defined, the rest is defined by the user.

Values:

enumerator CK_CITY_MODE_KEEP_CURRENT

Keep the current mode.

enum ck_direction_t

Direction enum.

Values:

enumerator CK_DIRECTION_RECEIVE

Receive direction.

enumerator CK_DIRECTION_TRANSMIT

Transmit direction.

enum ck_list_type_t

Some list types for storing predefined data in a city, which can be used by the king to construct new pages or documents.

Values:

enumerator CK_LIST_BIT

Bit list.

enumerator CK_LIST_LINE

Line list.

enumerator CK_LIST_PAGE

Page list.

enumerator CK_LIST_DOCUMENT

Document list.

enum ck_envelope_action_t

Defines envelope actions for use with KP2.

Values:

enumerator CK_ENVELOPE_NO_ACTION
enumerator CK_ENVELOPE_ASSIGN

Assign envelope to folder.

enumerator CK_ENVELOPE_EXPEL

Expel envelope from previous assignment.

Envelope must be disabled in the same message for this to work.

enumerator CK_ENVELOPE_TRANSFER

Move envelope to new folder.

enum ck_document_action_t

Defines document actions for use with KP16.

Values:

enumerator CK_DOCUMENT_NO_ACTION
enumerator CK_DOCUMENT_REMOVE

Remove document from folder.

enumerator CK_DOCUMENT_INSERT

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

ck_err_t ck_check_action_mode(ck_action_mode_t mode)

Check if the specified action mode is a valid action mode.

Parameters:

mode – ck_action_mode_t to check.

Returns:

CK_ERR_INVALID_ACTION_MODE if mode is invalid.

Returns:

CK_OK on success.

ck_err_t ck_check_comm_mode(ck_comm_mode_t mode)

Check if the specified communication mode is a valid communication mode.

Parameters:

mode – ck_comm_mode_t to check.

Returns:

CK_ERR_INVALID_COMM_MODE if mode is invalid.

Returns:

CK_OK on success.

ck_err_t ck_check_list_type(ck_list_type_t type)

Check if the specified list type is valid.

Parameters:

type – ck_list_type_t to check.

Returns:

CK_ERR_INVALID_LIST_TYPE if type is invalid.

Returns:

CK_OK on success.

ck_err_t ck_check_can_bit_timing(const ck_can_bit_timing_t *bit_timing)

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.

Parameters:

bit_timing – pointer to parameters to check.

Returns:

CK_ERR_INVALID_CAN_BIT_TIMING if bit_timing is invalid.

Returns:

CK_OK on success.

ck_letter_t ck_default_letter(void)

Returns a CAN Kingdom default letter.

The default letter is a letter with CAN ID 2031 and 8 lines each containing 0xAA.

Returns:

the created letter.

ck_can_bit_timing_t ck_default_bit_timing(void)

Returns bit timing parameters specifying a bit rate of 125 Kbit/s and a sampling point of 87.5%.

Returns:

the ck_can_bit_timing_t.

struct ck_page_t
#include <types.h>

Page structure, represents the data in a CAN frame.

Public Members

uint8_t line_count

Number of lines on page.

uint8_t lines[CK_MAX_LINES_PER_PAGE]

Line data.

struct ck_envelope_t
#include <types.h>

Envelope structure, represents the header of a CAN frame.

Public Members

uint32_t envelope_no

CAN ID.

bool enable

Whether envelope is enabled or not.

bool has_extended_id

Whether envelope uses standard or extended CAN IDs.

bool is_remote

Remote envelope (RTR bit).

bool is_compressed

Compressed envelope. Not supported at the moment.

struct ck_letter_t
#include <types.h>

Letter structure, for creating CAN messages from folders.

Public Members

ck_envelope_t envelope
ck_page_t page
struct ck_document_t
#include <types.h>

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

ck_direction_t direction

Direction of the document.

uint8_t page_count

How many pages the document contains.

ck_page_t *pages[CK_MAX_PAGES_PER_DOCUMENT]

List of pointers to pages.

struct ck_folder_t
#include <types.h>

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

uint8_t folder_no

Folder number.

uint8_t doc_list_no

Document list number.

uint8_t doc_no

Document number.

ck_direction_t direction

Direction of the folder.

uint8_t dlc

CAN DLC.

bool has_rtr

CAN RTR bit.

bool enable

Folder enabled / disabled.

uint8_t envelope_count

How many envelopes have been assigned.

ck_envelope_t envelopes[CK_MAX_ENVELOPES_PER_FOLDER]

Assigned envelopes.

The specification allows more than one envelope to be assigned to a folder.

struct ck_list_t
#include <types.h>

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

CK_LIST_BIT

uint8_t *

CK_LIST_LINE

uint8_t *

CK_LIST_PAGE

ck_page_t *

CK_LIST_DOCUMENT

ck_document_t *

The uint8_t * in a CK_LIST_BIT 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

ck_list_type_t type

The type of items this list contains.

ck_direction_t direction

CK_DIRECTION_RECEIVE or CK_DIRECTION_TRANSMIT.

uint8_t list_no

List number. Must be unique for each direction and type.

uint8_t record_count

Number of records in the list.

void *records[CK_MAX_RECORDS_PER_LIST]

List of pointers to records.

struct ck_can_bit_timing_t
#include <types.h>

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

uint8_t prescaler

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

uint8_t time_quanta
uint8_t phase_seg2

Number of time quanta.

uint8_t sjw

Phase segment 2.

Synchronization jump width, 1 <= sjw <= 4. Must also be less than the minimum of phase_seg1 and phase_seg2.

mayor.h

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

CK_MAX_GROUPS_PER_CITY

Limited to 6 groups for ease of implementation.

Can be redefined during compilation if wanted.

Functions

ck_err_t ck_mayor_init(const ck_mayor_t *mayor)

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.

Parameters:

mayor – parameters for setting up the mayor.

Returns:

CK_ERR_MISSING_PARAMETER if some required parameter is not set.

Returns:

CK_ERR_INVALID_PARAMETER if some parameter is set incorrectly.

Returns:

CK_ERR_ITEM_NOT_FOUND if missing a requred list.

Returns:

CK_ERR_CAPACITY_REACHED if a requred list is too small.

Returns:

CK_OK on success.

ck_err_t ck_process_kings_letter(const ck_letter_t *letter)

Parse the king’s letter and act on it.

Not all return codes are listed, since some of the errors may be user defined.

Parameters:

letter – the received king’s letter.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_INVALID_KINGS_LETTER if the letter is not a valid king’s letter.

Returns:

CK_ERR_UNSUPPORTED_KINGS_PAGE if the letter contains a king’s page not supported by this implementation.

Returns:

CK_ERR_CAPACITY_REACHED if the king tries to assign more envelopes than possible.

Returns:

CK_ERR_INVALID_CAN_ID received CAN ID is out of bounds.

Returns:

CK_ERR_INVALID_FOLDER_NUMBER reserved folder number was received.

Returns:

CK_ERR_ITEM_NOT_FOUND folder, record or mayor’s page not found.

Returns:

CK_ERR_SEND_FAILED failed to send mayor’s page.

Returns:

CK_ERR_INVALID_LIST_TYPE if an accessed list doesn’t have a valid type.

Returns:

CK_ERR_INVALID_PARAMETER some parameters on the king’s page are invalid, or the passed letter is NULL.

Returns:

CK_OK on success or if the letter is not addressed to the caller.

ck_err_t ck_add_mayors_page(ck_page_t *page)

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.

Parameters:

page – the page to add to the mayor’s document.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_INVALID_PARAMETER if page is NULL.

Returns:

CK_ERR_CAPACITY_REACHED if the mayor’s document cannot hold more pages.

Returns:

CK_OK on success.

ck_err_t ck_send_document(uint8_t folder_no)

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:

  1. Letter with envelope 0xA, page 0

  2. Letter with envelope 0xA, page 1

  3. Letter with envelope 0xB, page 0

  4. Letter with envelope 0xB, page 1

Parameters:

folder_no – the requested folder number.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_ITEM_NOT_FOUND if the folder or it’s document don’t exist.

Returns:

CK_ERR_SEND_FAILED if sending a letter fails.

Returns:

CK_OK on success or if document is not sent due to being a receive document or in a receive folder.

ck_err_t ck_send_mayors_page(uint8_t page_no)

Sends the specified mayor’s page.

Parameters:

page_no – mayor’s page number.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_ITEM_NOT_FOUND if the page doesn’t exist.

Returns:

CK_ERR_SEND_FAILED if sending the letter fails.

Returns:

CK_OK on success or if mayor’s folder is disabled for some reason.

ck_err_t ck_is_kings_envelope(const ck_envelope_t *envelope)

Checks if the envelope is assigned to the king’s folder.

Parameters:

envelope – envelope to check.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_FALSE if it’s not assigned.

Returns:

CK_OK if it’s assigned.

ck_err_t ck_get_envelopes_folder(const ck_envelope_t *envelope, ck_folder_t **folder)

Tries to find the folder that the given envelope is assigned to.

Parameters:

  • envelope – envelope to check.

  • folder – to which the envelope is assigned, if found.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_FALSE if the envelope is not assigned to any folder.

Returns:

CK_OK if it’s assigned.

ck_err_t ck_set_comm_mode(ck_comm_mode_t mode)

Set the communication mode.

Parameters:

mode – the desired communication mode.

Returns:

ck_apply_comm_mode() return codes.

ck_comm_mode_t ck_get_comm_mode(void)

Return the currently set communication mode.

Returned value is not valid if mayor is not initialized.

uint32_t ck_get_base_number(void)

Returns the current base number.

Returned value is not valid if mayor is not initialized.

ck_err_t ck_set_base_number(uint32_t base_no, bool has_extended_id)

Sets the base number.

Parameters:

  • base_no – the base number to set.

  • has_extended_id – whether the base number should use extended CAN IDs.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_INVALID_CAN_ID if the base number is not a valid CAN ID.

Returns:

CK_OK on success.

ck_err_t ck_is_default_letter(ck_letter_t *letter)

Checks if the given letter is the default letter.

Parameters:

letter – the letter to check.

Returns:

CK_ERR_FALSE if it’s not the default letter.

Returns:

CK_OK if it is.

ck_err_t ck_default_letter_received(void)

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.

Returns:

ck_set_comm_mode() return codes.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_OK on success.

ck_err_t ck_default_letter_timeout(void)

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.

Returns:

ck_set_comm_mode() return codes.

Returns:

ck_load_bit_timing() return codes.

Returns:

ck_set_bit_timing() return codes.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_OK on success.

ck_err_t ck_correct_letter_received(void)

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.

Returns:

ck_send_mayors_page() return codes.

Returns:

ck_save_bit_timing() return codes.

Returns:

CK_ERR_NOT_INITIALIZED if ck_mayor_init() has not been called.

Returns:

CK_ERR_SET_MODE_FAILED if failed setting the communication mode.

Returns:

CK_OK on success.

struct ck_mayor_t
#include <mayor.h>

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

uint64_t ean_no

40-bit EAN-13 number.

uint64_t serial_no

40-bit serial number.

uint8_t city_address

The city address. Must not be 0. Can be changed by the king.

uint8_t group_addresses[CK_MAX_GROUPS_PER_CITY]

The group addresses.

Can be changed by the king. The city always belongs to group 0 as well.

ck_err_t (*set_action_mode)(ck_action_mode_t)

Function for setting the action mode.

Should return CK_OK on success.

ck_err_t (*set_city_mode)(ck_city_mode_t)

Function for setting the city mode.

City modes are defined by the mayor. Should return CK_OK on success.

void (*start_200ms_timer)(void)

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.

uint8_t folder_count

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().

ck_folder_t *folders

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.

uint8_t list_count

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.

ck_list_t *lists

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().

king.h

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

ck_err_t ck_create_kings_page_0(const ck_kp0_args_t *args, ck_page_t *page)

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.

Parameters:

  • args – ck_kp0_args_t value with the desired values.

  • page – will be populated with the created king’s page.

Returns:

CK_ERR_INVALID_ACTION_MODE if the given action mode is invalid.

Returns:

CK_ERR_INVALID_COMM_MODE if the given comm mode is invalid.

Returns:

CK_OK on success.

ck_err_t ck_create_kings_page_1(const ck_kp1_args_t *args, ck_page_t *page)

KP1 is the initiating page.

It provides the base number and asks for mayor’s response.

Parameters:

  • args – ck_kp1_args_t value with the desired values.

  • page – will be populated with the created king’s page.

Returns:

CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.

Returns:

CK_OK on success.

ck_err_t ck_create_kings_page_2(const ck_kp2_args_t *args, ck_page_t *page)

KP2 is used to assign, expel or transfer envelopes from/to folders.

Parameters:

  • args – ck_kp2_args_t value with the desired values.

  • page – will be populated with the created king’s page.

Returns:

CK_ERR_INCOMPATIBLE_PARAMS if some of the args are incompatible.

Returns:

CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.

Returns:

CK_OK on success.

ck_err_t ck_create_kings_page_8(uint8_t address, const ck_can_bit_timing_t *bit_timing, ck_page_t *page)

KP8 is used to set the CAN bit timing settings for a city.

Parameters:

  • 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.

Returns:

CK_ERR_INCOMPATIBLE_PARAMS if some of the args are incompatible.

Returns:

CK_ERR_INVALID_CAN_ID if the given CAN ID is out of bounds.

Returns:

CK_OK on success.

ck_err_t ck_create_kings_page_16(const ck_kp16_args_t *args, ck_page_t *page)

KP16 Sets the folder label and/or places a document into a folder.

Parameters:

  • args – ck_kp16_args_t value with the desired values.

  • page – will be populated with the created king’s page.

Returns:

CK_ERR_INVALID_FOLDER_NUMBER if a reserved folder number is given.

Returns:

CK_ERR_INVALID_CAN_DLC if the given DLC value is out of bounds.

Returns:

CK_OK on success.

ck_err_t ck_create_kings_page_17(const ck_kp17_args_t *args, ck_page_t *page)

KP17 Creates a document, a page or a line from predefined page, line, or bit lists.

Parameters:

  • args – ck_kp17_args_t value with the desired values.

  • page – will be populated with the created king’s page.

Returns:

CK_ERR_INVALID_LIST_TYPE if the given list type is invalid.

Returns:

CK_OK on success.

struct ck_kp0_args_t
#include <king.h>

Struct defining parameters for king’s page 0.

Public Members

uint8_t address

City or group address.

ck_action_mode_t action_mode

Action mode.

ck_comm_mode_t comm_mode

Communication mode.

ck_comm_flags_t comm_flags

Communication mode flags to set.

ck_city_mode_t city_mode

City mode.

Only CK_CITY_MODE_KEEP_CURRENT is predefined. Modes are defined by mayor and specified in their city’s documentation.

struct ck_kp1_args_t
#include <king.h>

Struct defining parameters for king’s page 1.

Public Members

uint8_t address

City or group address.

uint8_t mayor_response_no

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.

uint32_t base_no

Base number of kingdom. This should be defined by the king.

bool has_extended_id

Whether to use standard or extended CAN IDs.

struct ck_kp2_args_t
#include <king.h>

Struct defining parameters for king’s page 2.

Compressed envelopes are not implemented.

Public Members

uint8_t address

City or group address.

ck_envelope_t envelope

Envelope argument.

uint8_t folder_no

Folder number.

ck_envelope_action_t envelope_action

Envelope action to take.

struct ck_kp16_args_t
#include <king.h>

Struct defining parameters for king’s page 16.

Public Members

uint8_t address

City or group address.

uint8_t folder_no

Folder number.

uint8_t dlc

at most CK_CAN_MAX_DLC.

bool has_rtr

The rtr bit.

ck_direction_t direction

Direction of the target document.

ck_document_action_t document_action

Document action to take.

bool enable_folder

Enable use of the folder.

uint8_t list_no

Document list number.

uint8_t document_no

Document number in list.

struct ck_kp17_args_t
#include <king.h>

Struct defining parameters for king’s page 17.

We use the term “record” to denote an item in a list.

Public Members

uint8_t address

City or group address.

ck_direction_t direction

Direction of the source and target records.

ck_list_type_t list_type

Target list type.

uint8_t source_list_no

Source list number.

uint8_t source_record_no

Source record number.

uint8_t target_list_no

Target list number.

uint8_t target_record_no

Target record number.

uint8_t position

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.