Class and Methods¶

Library provides one class DigiProtocol. On AVR as in most Arduino libraries object of this already exist and this should be the only object from this library - because its operate on the only one interface. All methods on AVR are connected with this object named DigiProtocol e.g. DigiProtocol.begin()

However on PC you should create object yourself. There can be multiple objects. One for one connected device at same time.

begin()¶

void begin()

Begins emulating USB interface. begin() must be called first e.g. in setup

Parameters¶

Nothing

Returns¶

Nothing

available()¶

int available()

Returns size of incoming message taken from protocol frame. It calls getRequest() method to keep connection.

Parameters¶

Nothing

Returns¶

-1 if there is no waiting message available in buffer

number of bytes of incoming message

read()¶

int read()

Tries to read one byte of incoming message from buffer

Parameters¶

Nothing

Returns¶

The first byte of incoming message (or -1 if no data is available e.g. message is being still in transmission).

sendMessage()¶

void sendMessage(char* message)

Sends message using protocol frame. Currently only text data can be sent. So you have to change other types to char array by your own.

Parameters¶

message: the message to send. Allowed data type: char array

Returns¶

Nothing

sendRequest()¶

void SendRequest(uint8_t request)

Sends request i.e. 8-bit instruction defined in library. Mainly request are used by embedded methods but its public in case you have to send one manually.

Check list of request available in documentation.

Parameters¶

request: the request to send.

Returns¶

Nothing

clear()¶

void clear()

Clear all bytes waiting in buffer. Use this method when incoming message is bigger than your message-limit, to clear buffer and in any situations when you want to ignore waiting bytes.

Parameters¶

Nothing

Returns¶

Nothing

error()¶

int error()

Check error status. Should be called every time when message has been read to check CRC value status.

Parameters¶

Nothing

Returns¶

Returns DP_NO_ERROR when no error. Possible errors:

DP_ERROR_WRONG_PROTOCOL when incoming byte can’t be recognised as library request
DP_ERROR_CORRUPTED_DATA when CRC value is not equal to 0

refresh()¶

void refresh()

This is wrapper function for getRequest(). Just to make it similar to DigiUSB structure. Check getRequest() for details.

Parameters¶

Nothing

Returns¶

Nothing

getRequest()¶

void getRequest()

Very important method. It keeps connection over USB, also its implementation of communication loop which handle requests. Make sure to call this method in loop in your program.

Parameters¶

Nothing

Returns¶

Nothing

delay()¶

void delay(long ms)

Pauses the program for the amount of time (in milliseconds) specified as parameter. Please make sure to use this delay() instead of Arduino function when using DigiProtocol. Because this method keep connection in the background. And calls communication loop implemented in getRequest()

Parameters¶

ms the number of milliseconds to pause. Allowed data types: long.

Returns¶

Nothing

PC Methods¶

DigiProtocol()
open()
close()
error()
isOpen()
listDevices()
sendMessage()
readMessage()
sendRequest()
_readByte()
_readID()

On PC some methods has optional parameters. It means that it has default value. You can call this method without giving this parameter but only if it’s the last one. (You can skip one or more of the last parameters). For example all timeouts are optional, and by default methods has 1 second timeout.

DigiProtocol()¶

DigiProtocol(std::string ID="", int timeout=1000)

Constructor of DigiProtocol class. Opens connection with device searched by given ID

Parameters¶

ID (optional) - ID of device to connect with. Can be in 2-byte format of product type (will connect with first device of this type) or full 10-byte format unique for every device. If no parameter given or given ID is empty string, connection will be opened with first device with VID/PID equal to DigiSpark ID pair. (default value: “”)
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

Nothing

open()¶

int open(std::string ID="", int timeout=1000)

Class constructor opens connection itself, but if you want change device in same object you can call close() and use open() to start new connection. This method is also useful if there was error in connection and there is no device connected after creating object. (you can check connection with isOpen() method)

Parameters¶

ID (optional) - ID of device to connect with. Can be in 2-byte format of product type (will connect with first device of this type) or full 10-byte format unique for every device. If no parameter given or given ID is empty string, connection will be opened with first device with VID/PID equal to DigiSpark ID pair. (default value: “”)
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

DP_NO_ERROR on successful connection with device.
DP_ERROR_NO_DEVICE when couldn’t find device with specified ID
DP_ACCES_ERROR when couldn’t create USB device list

close()¶

void close()

Closes connection with device. You should call this method every time when you want to change device in same object of this class.

Parameters¶

Nothing

Returns¶

Nothing

error()¶

int error()

Returns error code or DP_NO_ERROR when no error. Currently used only for inform about errors inside constructor, but rather than error() method prefer call isOpen() instead, because isOpen() checks connection and send ping-request to device.

Parameters¶

Nothing

Returns¶

Error code or DP_NO_ERROR on clear status.

isOpen()¶

bool isOpen(int timeout=1000)

Checks connection status, sends ping-request (no more than once every second)

Parameters¶

timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

True if device answered last ping.

False if connection is closed or device is not responding

listDevices()¶

int listDevices(std::vector<std::string> &IDlist, int timeout=1000)

Creates list of devices plugged into the computer. Uses std::vector which is given as reference in parameter

Parameters¶

&IDlist - Reference to string vector where ID’s will be added
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

DP_NO_ERROR on successful connection with device.
DP_ACCES_ERROR when couldn’t create USB device list

sendMessage()¶

int sendMessage(std::string message)

Sends message to connected device via protocol-frame

Parameters¶

message - string with message to sent

Returns¶

Error code or DP_NO_ERROR on clear status.

readMessage()¶

int readMessage(std::string &message, int timeout=1000)

Tries read to message from device

Parameters¶

&message - reference to string buffer where message will be written
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

Number of read bytes or DP_NO_DATA if there is data to read or error code which that occured. DP_ERROR_DEVICE_BUSY, DP_ERROR_NO_RESPONSE, DP_ERROR_TIMEOUT, DP_ERROR_WRONG_SIZE, DP_ERROR_CORRUPTED_DATA. See error list for details.

sendRequest()¶

int sendRequest(uint8_t request, int timeout=1000)

Sends request, see list of defined requests for details.

Parameters¶

request - request to be sent. Allowed data type: uint8_t
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

Nothing

_readByte()¶

int _readByte(uint8_t &buffer, int timeout=1000)

Method to read one byte from device message. You shouldn’t use it, because it can damage protocol-frame of incoming message, but it’s left as public method in case you really need to use this method.

Parameters¶

&buffer - reference to uint8_t buffer for one byte of message
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

Error code. See Libusb API for details (this method doesn’t return DP_ERROR codes)

_readID()¶

int _readID(std::string &ID, int timeout=1000)

read ID of currently connected device

Parameters¶

&ID - reference to string where ID has to be written
timeout (optional) - timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. (default value: 1000)

Returns¶

DP_NO_ERROR on clear read ID. Error code otherwise e.g. DP_ERROR_DEVICE_BUSY, DP_ERROR_TIMEOUT, DP_EEPROM_ERROR, DP_NEW_DEVICE. See Error list for details.