
C API
============================

The simplyCAN API provides a simple programming interface for the development
of CAN applications on Windows PCs and on Linux PCs.


Types and Macros
----------------


### simply_last_error_t

Error codes of the API functions.
- Return value code 0 indicates that no error occured.
- Actual errors have a negative value code.
- Non-critical errors have a positive value code.

```c
typedef enum _simply_last_error {
  SIMPLY_S_NO_ERROR                       =   0,      /*  No error occurred */
  SIMPLY_E_SERIAL_OPEN                    =  -1,      /*  Unable to open the serial port */
  SIMPLY_E_SERIAL_ACCESS                  =  -2,      /*  Access on serial port denied */
  SIMPLY_E_SERIAL_CLOSED                  =  -3,      /*  Serial communication port is closed */
  SIMPLY_E_SERIAL_COMM                    =  -4,      /*  Serial communication error */
  SIMPLY_E_CMND_REQ_UNKNOWN               =  -5,      /*  Command unknown on device */
  SIMPLY_E_CMND_RESP_TIMEOUT              =  -6,      /*  Command response timeout reached */
  SIMPLY_E_CMND_RESP_UNEXPECTED           =  -7,      /*  Unexpected command response received */
  SIMPLY_E_CMND_RESP_ERROR                =  -8,      /*  Command response error */
  SIMPLY_E_INVALID_PROTOCOL_VERSION       =  -9,      /*  Invalid simplyCAN protocol version */
  SIMPLY_E_INVALID_FW_VERSION             =  -10,     /*  Invalid device firmware version */
  SIMPLY_E_INVALID_PRODUCT_STRING         =  -11,     /*  Invalid simplyCAN product string */
  SIMPLY_E_CAN_INVALID_STATE              =  -12,     /*  Invalid CAN state */
  SIMPLY_E_CAN_INVALID_BAUDRATE           =  -13,     /*  Invalid CAN baud-rate */
  SIMPLY_E_TX_BUSY                        =  -14,     /*  Message could not be sent. TX is busy */
  SIMPLY_E_API_BUSY                       =  -15,     /*  API is busy */
} simply_last_error_t;
```


Functions
---------


### simply_open()

Opens the serial communication interface. The message filter of the CAN controller is opened
for all message identifiers.

    DLL bool simply_open(char *serial_port);


*Parameter:*

* `serial_port` - (IN) Name of the serial communication port (e.g. COM1 or /dev/ttyACM0). Use the simplyCAN bus monitor to detect on which serial COM port the simplyCAN is connected. With Windows it is also possible to use the device manager and with Linux the command "ls -l /dev/serial/by-id".

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_close()

Closes the serial communication interface and resets the CAN controller.

    DLL bool simply_close(void);


*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_initialize_can()

Initializes the CAN controller.

    DLL bool simply_initialize_can(uint16_t bitrate);


*Parameter:*

* `bitrate` - (IN) CAN bitrate as integer value, possible values: 10, 20, 50, 125, 250, 500, 800, 1000

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_identify()

Gets firmware and hardware information about the simplyCAN device.

    DLL bool simply_identify(identification_t *p_identification);


*Parameter:*

* `p_identification` - (OUT) Pointer to the identification structure

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_start_can()

Starts the CAN controller. Sets the CAN controller into running mode and clears the CAN
message FIFOs. In running mode CAN messages can be transmitted and received.

    DLL bool simply_start_can(void);


*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_stop_can()

Stops the CAN controller. Sets the CAN controller into init mode. Does not reset the message
filter of the CAN controller. Only stop the CAN controller when the CAN_STATUS_PENDING flag
is not set.

    DLL bool simply_stop_can(void);


*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_reset_can()

Resets the CAN controller (hardware reset) and clears the message filter (open for all message
identifiers). Sets the CAN controller into init mode.

    DLL bool simply_reset_can(void);


*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_can_status()

Gets the status of the CAN controller.

    DLL bool simply_can_status(can_sts_t *can_sts);


*Parameter:*

* `can_sts` - (OUT) status as bit coded 16 bit value (see can_sts_t)

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_set_filter()

Sets the 11 or 29 bit message filter of the CAN controller. To set the 29 bit message filter,
the MSB in parameter value must be set.

    DLL bool simply_set_filter(uint32_t mask, uint32_t value);


*Parameter:*

* `mask` - (IN) 11 or 29 bit CAN message identifier mask
* `value` - (IN) 11 or 29 bit CAN message identifier value, set MSB to set the 29 bit message filter

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_receive()

Receives a single CAN message.

    DLL int8_t simply_receive(can_msg_t *can_msg);


*Parameter:*

* `can_msg` - (OUT) Pointer to the CAN message structure the received CAN message is copied to

*Return value:*

* `1` - Message received
* `0` - No message available in the receive queue
* `-1` - Error occurred, call simply_get_last_error for more information.



### simply_send()

Writes a CAN message to the transmit FIFO. To check if the message is transmitted, request
the CAN status with simply_can_status.

    DLL bool simply_send(can_msg_t *can_msg);


*Parameter:*

* `can_msg` - (IN) Pointer to a CAN message to be transmitted (see can_msg_t)

*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_flush_tx_fifo()

Flush the tx fifo to speed up the transmission of cached CAN messages.

    DLL bool simply_flush_tx_fifo(void);


*Return value:*

* `true` - Function succeeded
* `false` - Error occurred, call simply_get_last_error for more information.



### simply_get_last_error()

Gets the last error code. After reading the error code with simply_get_last_error the error
code is set to 0. Each error can only be read once.

    DLL int16_t simply_get_last_error(void);


*Return value:*

* `0` - No error occurred
* `<0` - Error occurred (see simply_last_error_t)


