CSP API

group CSP

Typedefs

typedef void *csp_memptr_t
typedef csp_memptr_t (*csp_memcpy_fnc_t)(csp_memptr_t, const csp_memptr_t, size_t)
typedef void (*csp_debug_hook_func_t)(csp_debug_level_t level, const char *format, va_list args)

Set csp_debug hook function.

Parameters
  • f: Hook function

Functions

int csp_init(uint8_t my_node_address)

csp_init Start up the can-space protocol

Parameters
  • my_node_address: The CSP node address

void csp_terminate(void)
void csp_set_address(uint8_t addr)

csp_set_address Set the systems own address

Parameters
  • addr: The new address of the system

uint8_t csp_get_address(void)

csp_get_address Get the systems own address

Return
The current address of the system

void csp_set_hostname(char *hostname)

csp_set_hostname Set subsystem hostname.

This function takes a pointer to a string, which should remain static

Parameters
  • hostname: Hostname to set

char *csp_get_hostname(void)

csp_get_hostname Get current subsystem hostname.

Return
Pointer to char array with current hostname.

void csp_set_model(char *model)

csp_set_model Set subsystem model name.

This function takes a pointer to a string, which should remain static

Parameters
  • model: Model name to set

char *csp_get_model(void)

csp_get_model Get current model name.

Return
Pointer to char array with current model name.

void csp_set_revision(char *revision)

csp_set_revision Set subsystem revision.

This can be used to override the CMP revision field. This function takes a pointer to a string, which should remain static

Parameters
  • revision: Revision name to set

char *csp_get_revision(void)

csp_get_revision Get subsystem revision.

Return
Pointer to char array with software revision.

csp_socket_t *csp_socket(uint32_t opts)

csp_socket Create CSP socket endpoint

Return
Pointer to socket on success, NULL on failure
Parameters
  • opts: Socket options

csp_conn_t *csp_accept(csp_socket_t *socket, uint32_t timeout)

Wait for a new connection on a socket created by csp_socket.

Return
Return pointer to csp_conn_t or NULL if timeout was reached
Parameters
  • socket: Socket to accept connections on
  • timeout: use CSP_MAX_DELAY for infinite timeout

csp_packet_t *csp_read(csp_conn_t *conn, uint32_t timeout)

Read data from a connection This fuction uses the RX queue of a connection to receive a packet If no packet is available and a timeout has been specified The call will block.

Do NOT call this from ISR

Return
Returns pointer to csp_packet_t, which you MUST free yourself, either by calling csp_buffer_free() or reusing the buffer for a new csp_send.
Parameters
  • conn: pointer to connection
  • timeout: timeout in ms, use CSP_MAX_DELAY for infinite blocking time

int csp_send(csp_conn_t *conn, csp_packet_t *packet, uint32_t timeout)

Send a packet on an already established connection.

Return
returns 1 if successful and 0 otherwise. you MUST free the frame yourself if the transmission was not successful.
Parameters
  • conn: pointer to connection
  • packet: pointer to packet,
  • timeout: a timeout to wait for TX to complete. NOTE: not all underlying drivers supports flow-control.

int csp_send_prio(uint8_t prio, csp_conn_t *conn, csp_packet_t *packet, uint32_t timeout)

Send a packet on an already established connection, and change the default priority of the connection.

Note
When using this function, the priority of the connection will change. If you need to change it back use another call to csp_send_prio, or ensure that all packets sent on a given connection is using send_prio call.
Return
returns 1 if successful and 0 otherwise. you MUST free the frame yourself if the transmission was not successful.
Parameters
  • prio: csp priority
  • conn: pointer to connection
  • packet: pointer to packet,
  • timeout: a timeout to wait for TX to complete. NOTE: not all underlying drivers supports flow-control.

int csp_transaction(uint8_t prio, uint8_t dest, uint8_t port, uint32_t timeout, void *outbuf, int outlen, void *inbuf, int inlen)

Perform an entire request/reply transaction Copies both input buffer and reply to output buffeer.

Also makes the connection and closes it again

Return
Return 1 or reply size if successful, 0 if error or incoming length does not match or -1 if timeout was reached
Parameters
  • prio: CSP Prio
  • dest: CSP Dest
  • port: CSP Port
  • timeout: timeout in ms
  • outbuf: pointer to outgoing data buffer
  • outlen: length of request to send
  • inbuf: pointer to incoming data buffer
  • inlen: length of expected reply, -1 for unknown size (note inbuf MUST be large enough)

int csp_transaction_persistent(csp_conn_t *conn, uint32_t timeout, void *outbuf, int outlen, void *inbuf, int inlen)

Use an existing connection to perform a transaction, This is only possible if the next packet is on the same port and destination!

Return
Parameters
  • conn: pointer to connection structure
  • timeout: timeout in ms
  • outbuf: pointer to outgoing data buffer
  • outlen: length of request to send
  • inbuf: pointer to incoming data buffer
  • inlen: length of expected reply, -1 for unknown size (note inbuf MUST be large enough)

csp_packet_t *csp_recvfrom(csp_socket_t *socket, uint32_t timeout)

Read data from a connection-less server socket This fuction uses the socket directly to receive a frame If no packet is available and a timeout has been specified the call will block.

Do NOT call this from ISR

Return
Returns pointer to csp_packet_t, which you MUST free yourself, either by calling csp_buffer_free() or reusing the buffer for a new csp_send.

int csp_sendto(uint8_t prio, uint8_t dest, uint8_t dport, uint8_t src_port, uint32_t opts, csp_packet_t *packet, uint32_t timeout)

Send a packet without previously opening a connection.

Return
-1 if error (you must free packet), 0 if OK (you must discard pointer)
Parameters
  • prio: CSP_PRIO_x
  • dest: destination node
  • dport: destination port
  • src_port: source port
  • opts: CSP_O_x
  • packet: pointer to packet
  • timeout: timeout used by interfaces with blocking send

int csp_sendto_reply(csp_packet_t *request_packet, csp_packet_t *reply_packet, uint32_t opts, uint32_t timeout)

Send a packet as a direct reply to the source of an incoming packet, but still without holding an entire connection.

Return
-1 if error (you must free packet), 0 if OK (you must discard pointer)
Parameters
  • request_packet: pointer to packet to reply to
  • reply_packet: actual reply data
  • opts: CSP_O_x
  • timeout: timeout used by interfaces with blocking send

csp_conn_t *csp_connect(uint8_t prio, uint8_t dest, uint8_t dport, uint32_t timeout, uint32_t opts)

csp_connect Used to establish outgoing connections This function searches the port table for free slots and finds an unused connection from the connection pool There is no handshake in the CSP protocol

Return
a pointer to a new connection or NULL
Parameters
  • prio: Connection priority.
  • dest: Destination address.
  • dport: Destination port.
  • timeout: Timeout in ms.
  • opts: Connection options.

int csp_close(csp_conn_t *conn)

csp_close Closes a given connection and frees buffers used.

Return
CSP_ERR_NONE if connection was closed. Otherwise, an err code is returned.
Parameters
  • conn: pointer to connection structure

void csp_close_socket(csp_socket_t *socket)

Closes a given socket and frees queue used.

Parameters
  • socket: pointer to socket structure

int csp_conn_dport(csp_conn_t *conn)

Return
destination port of an incoming connection
Parameters
  • conn: pointer to connection structure

int csp_conn_sport(csp_conn_t *conn)

Return
source port of an incoming connection
Parameters
  • conn: pointer to connection structure

int csp_conn_dst(csp_conn_t *conn)

Return
destination address of an incoming connection
Parameters
  • conn: pointer to connection structure

int csp_conn_src(csp_conn_t *conn)

Return
source address of an incoming connection
Parameters
  • conn: pointer to connection structure

int csp_conn_flags(csp_conn_t *conn)

Return
flags field of an incoming connection
Parameters
  • conn: pointer to connection structure

int csp_conn_check_alive(csp_conn_t *conn)

Return
CSP_ERR_NONE if connection is still active & valid. Otherwise, an err code is returned.
Parameters
  • conn: pointer to connection structure

int csp_listen(csp_socket_t *socket, size_t conn_queue_length)

Set socket to listen for incoming connections.

Return
0 on success, -1 on error.
Parameters
  • socket: Socket to enable listening on
  • conn_queue_length: Length of backlog connection queue

int csp_bind(csp_socket_t *socket, uint8_t port)

Bind port to socket.

Return
0 on success, -1 on error.
Parameters
  • socket: Socket to bind port to
  • port: Port number to bind

int csp_route_start_task(unsigned int task_stack_size, unsigned int priority)

Start the router task.

Parameters
  • task_stack_size: The number of portStackType to allocate. This only affects FreeRTOS systems.
  • priority: The OS task priority of the router

void csp_route_end_task()

Ends the router task.

int csp_route_work(uint32_t timeout)

Call the router worker function manually (without the router task) This must be run inside a loop or called periodically for the csp router to work.

Use this function instead of calling and starting the router task.

Return
-1 if no packet was processed, 0 otherwise
Parameters
  • timeout: max blocking time

int csp_bridge_start(unsigned int task_stack_size, unsigned int task_priority, csp_iface_t *_if_a, csp_iface_t *_if_b)

Start the bridge task.

Return
CSP_ERR type
Parameters
  • task_stack_size: The number of portStackType to allocate. This only affects FreeRTOS systems.
  • priority: The OS task priority of the router
  • _if_a: pointer to first side
  • _if_b: pointer to second side

int csp_promisc_enable(unsigned int buf_size)

Enable promiscuous mode packet queue This function is used to enable promiscuous mode for the router.

If enabled, a copy of all incoming packets are placed in a queue that can be read with csp_promisc_get(). Not all interface drivers support promiscuous mode.

Parameters
  • buf_size: Size of buffer for incoming packets

void csp_promisc_disable(void)

Disable promiscuous mode.

If the queue was initialised prior to this, it can be re-enabled by calling promisc_enable(0)

csp_packet_t *csp_promisc_read(uint32_t timeout)

Get packet from promiscuous mode packet queue Returns the first packet from the promiscuous mode packet queue.

The queue is FIFO, so the returned packet is the oldest one in the queue.

Parameters
  • timeout: Timeout in ms to wait for a new packet

int csp_sfp_send(csp_conn_t *conn, void *data, int totalsize, int mtu, uint32_t timeout)

Send multiple packets using the simple fragmentation protocol CSP will add total size and offset to all packets This can be read by the client using the csp_sfp_recv, if the CSP_FFRAG flag is set.

Return
0 if OK, -1 if ERR
Parameters
  • conn: pointer to connection
  • data: pointer to data to send
  • totalsize: size of data to send
  • mtu: maximum transfer unit
  • timeout: timeout in ms to wait for csp_send()

int csp_sfp_send_own_memcpy(csp_conn_t *conn, void *data, int totalsize, int mtu, uint32_t timeout, void *(*memcpyfcn)(void *, const void *, size_t))

Same as csp_sfp_send but with option to supply your own memcpy function.

This is usefull if you wish to send data stored in flash memory or another location

Return
0 if OK, -1 if ERR
Parameters
  • conn: pointer to connection
  • data: pointer to data to send
  • totalsize: size of data to send
  • mtu: maximum transfer unit
  • timeout: timeout in ms to wait for csp_send()
  • memcpyfcnpointer: to memcpy function

int csp_sfp_recv(csp_conn_t *conn, void **dataout, int *datasize, uint32_t timeout)

This is the counterpart to the csp_sfp_send function.

Return
0 if OK, -1 if ERR
Parameters
  • conn: pointer to active conn, on which you expect to receive sfp packed data
  • dataout: pointer to NULL pointer, whill be overwritten with malloc pointer
  • datasize: actual size of received data
  • timeout: timeout in ms to wait for csp_recv()

int csp_sfp_recv_fp(csp_conn_t *conn, void **dataout, int *datasize, uint32_t timeout, csp_packet_t *first_packet)

This is the counterpart to the csp_sfp_send function.

Return
0 if OK, -1 if ERR
Parameters
  • conn: pointer to active conn, on which you expect to receive sfp packed data
  • dataout: pointer to NULL pointer, whill be overwritten with malloc pointer
  • datasize: actual size of received data
  • timeout: timeout in ms to wait for csp_recv()
  • first_packet: This is a pointer to the first SFP packet (previously received with csp_read)

void csp_service_handler(csp_conn_t *conn, csp_packet_t *packet)

If the given packet is a service-request (that is uses one of the csp service ports) it will be handled according to the CSP service handler.

This function will either use the packet buffer or delete it, so this function is typically called in the last “default” clause of a switch/case statement in a csp_listener task. In order to listen to csp service ports, bind your listener to the CSP_ANY port. This function may only be called from task context.

Parameters
  • conn: Pointer to the new connection
  • packet: Pointer to the first packet, obtained by using csp_read()

int csp_ping(uint8_t node, uint32_t timeout, unsigned int size, uint8_t conn_options)

Send a single ping/echo packet.

Return
>0 = Echo time in ms, -1 = ERR
Parameters
  • node: node id
  • timeout: timeout in ms
  • size: size of packet to transmit
  • conn_options: csp connection options

void csp_ping_noreply(uint8_t node)

Send a single ping/echo packet without waiting for reply.

Parameters
  • node: node id

void csp_ps(uint8_t node, uint32_t timeout)

Request process list.

Note
This is only available for FreeRTOS systems
Parameters
  • node: node id
  • timeout: timeout in ms

void csp_memfree(uint8_t node, uint32_t timeout)

Request amount of free memory.

Parameters
  • node: node id
  • timeout: timeout in ms

void csp_buf_free(uint8_t node, uint32_t timeout)

Request number of free buffer elements.

Parameters
  • node: node id
  • timeout: timeout in ms

void csp_reboot(uint8_t node)

Reboot subsystem.

Parameters
  • node: node id

void csp_shutdown(uint8_t node)

Shutdown subsystem.

Parameters
  • node: node id

void csp_uptime(uint8_t node, uint32_t timeout)

Request subsystem uptime.

Parameters
  • node: node id
  • timeout: timeout in ms

void csp_rdp_set_opt(unsigned int window_size, unsigned int conn_timeout_ms, unsigned int packet_timeout_ms, unsigned int delayed_acks, unsigned int ack_timeout, unsigned int ack_delay_count)

Set RDP options.

Parameters
  • window_size: Window size
  • conn_timeout_ms: Connection timeout in ms
  • packet_timeout_ms: Packet timeout in ms
  • delayed_acks: Enable/disable delayed acknowledgements
  • ack_timeout: Acknowledgement timeout when delayed ACKs is enabled
  • ack_delay_count: Send acknowledgement for every ack_delay_count packets

void csp_rdp_get_opt(unsigned int *window_size, unsigned int *conn_timeout_ms, unsigned int *packet_timeout_ms, unsigned int *delayed_acks, unsigned int *ack_timeout, unsigned int *ack_delay_count)

Get RDP options.

Parameters
  • window_size: Window size
  • conn_timeout_ms: Connection timeout in ms
  • packet_timeout_ms: Packet timeout in ms
  • delayed_acks: Enable/disable delayed acknowledgements
  • ack_timeout: Acknowledgement timeout when delayed ACKs is enabled
  • ack_delay_count: Send acknowledgement for every ack_delay_count packets

int csp_xtea_set_key(char *key, uint32_t keylen)

Set XTEA key.

Return
0 if key was successfully set, -1 otherwise
Parameters
  • key: Pointer to key array
  • keylen: Length of key

int csp_hmac_set_key(char *key, uint32_t keylen)

Set HMAC key.

Return
0 if key was successfully set, -1 otherwise
Parameters
  • key: Pointer to key array
  • keylen: Length of key

void csp_conn_print_table(void)

Print connection table.

void csp_buffer_print_table(void)

Print buffer usage table.

void csp_cmp_set_memcpy(csp_memcpy_fnc_t fnc)
void csp_debug_hook_set(csp_debug_hook_func_t f)