Library specification

Functions

You can use all regular Arduino functionalities with CanSat NeXT, as well as any Arduino libraries. Arduino functions can be found here: https://www.arduino.cc/reference/en/.

CanSat NeXT library adds several easy to use functions for using the different on-board resources, such as sensors, radio and the SD-card. The library comes with a set of example sketches that show how to use these functionalities. The list below also shows all available functions.

System Initialization Functions

CanSatInit

Function	uint8_t CanSatInit(uint8_t macAddress[6])
Return Type	`uint8_t`
Return Value	Returns 0 if initialization was successful, or non-zero if there was an error.
Parameters
	`uint8_t macAddress[6]`
	6-byte MAC address shared by the satellite and the ground station. This is an optional parameter - when it is not provided, the radio is not initialized. Used in example sketch: All
Description	This command is found in the `setup()` of almost all CanSat NeXT scripts. It is used to initialize the CanSatNeXT hardware, including the sensors and the SD-card. Additionally, if the `macAddress` is provided, it starts the radio and starts to listen for incoming messages. The MAC address should be shared by the ground station and the satellite. The MAC address can be chosen freely, but there are some non-valid addresses such as all bytes being `0x00`, `0x01`, and `0xFF`. If the init function is called with a non-valid address, it will report the problem to the Serial.

CanSatInit (simplified MAC-address specification)

Function	uint8_t CanSatInit(uint8_t macAddress)
Return Type	`uint8_t`
Return Value	Returns 0 if initialization was successful, or non-zero if there was an error.
Parameters
	`uint8_t macAddress`
	Last byte of the MAC-address, used to differentiate between different CanSat-GS pairs.
Description	This is a simplified version of the CanSatInit with MAC address, which sets the other bytes automatically to a known safe value. This enables the users to differentiate their Transmitter-Receiver pairs with just one value, which can be 0-255.

GroundStationInit

Function	uint8_t GroundStationInit(uint8_t macAddress[6])
Return Type	`uint8_t`
Return Value	Returns 0 if initialization was successful, or non-zero if there was an error.
Parameters
	`uint8_t macAddress[6]`
	6-byte MAC address shared by the satellite and the ground station.
Used in example sketch	Groundstation receive
Description	This is a close relative of the CanSatInit function, but it always requires the MAC address. This function only initializes the radio, not other systems. The ground station can be any ESP32 board, including any devboard or even another CanSat NeXT board.

GroundStationInit (simplified MAC-address specification)

Function	uint8_t GroundStationInit(uint8_t macAddress)
Return Type	`uint8_t`
Return Value	Returns 0 if initialization was successful, or non-zero if there was an error.
Parameters
	`uint8_t macAddress`
	Last byte of the MAC-address, used to differentiate between different CanSat-GS pairs.
Description	This is a simplified version of the GroundStationInit with MAC address, which sets the other bytes automatically to a known safe value. This enables the users to differentiate their Transmitter-Receiver pairs with just one value, which can be 0-255.

IMU Functions

readAcceleration

Function	uint8_t readAcceleration(float &x, float &y, float &z)
Return Type	`uint8_t`
Return Value	Returns 0 if measurement was successful.
Parameters
	`float &x, float &y, float &z`
	`float &x`: Address of a float variable where the x-axis data will be stored.
Used in example sketch	IMU
Description	This function can be used to read acceleration from the on-board IMU. The parameters are addresses to float variables for each axis. The example IMU shows how to use this function to read the acceleration. The acceleration is returned in units of G (9.81 m/s).

readAccelX

Function	float readAccelX()
Return Type	`float`
Return Value	Returns linear acceleration on X-axis in units of G.
Used in example sketch	IMU
Description	This function can be used to read acceleration from the on-board IMU on a specific axis. The example IMU shows how to use this function to read the acceleration. The acceleration is returned in units of G (9.81 m/s).

readAccelY

Function	float readAccelY()
Return Type	`float`
Return Value	Returns linear acceleration on Y-axis in units of G.
Used in example sketch	IMU
Description	This function can be used to read acceleration from the on-board IMU on a specific axis. The example IMU shows how to use this function to read the acceleration. The acceleration is returned in units of G (9.81 m/s).

readAccelZ

Function	float readAccelZ()
Return Type	`float`
Return Value	Returns linear acceleration on Z-axis in units of G.
Used in example sketch	IMU
Description	This function can be used to read acceleration from the on-board IMU on a specific axis. The example IMU shows how to use this function to read the acceleration. The acceleration is returned in units of G (9.81 m/s).

readGyro

Function	uint8_t readGyro(float &x, float &y, float &z)
Return Type	`uint8_t`
Return Value	Returns 0 if measurement was successful.
Parameters
	`float &x, float &y, float &z`
	`float &x`: Address of a float variable where the x-axis data will be stored.
Used in example sketch	IMU
Description	This function can be used to read angular velocity from the on-board IMU. The parameters are addresses to float variables for each axis. The example IMU shows how to use this function to read the angular velocity. The angular velocity is returned in units mrad/s.

readGyroX

Function	float readGyroX()
Return Type	`float`
Return Value	Returns angular velocity on X-axis in units of mrad/s.
Used in example sketch	IMU
Description	This function can be used to read angular velocity from the on-board IMU on a specific axis. The parameters are addresses to float variables for each axis. The angular velocity is returned in units mrad/s.

readGyroY

Function	float readGyroY()
Return Type	`float`
Return Value	Returns angular velocity on Y-axis in units of mrad/s.
Used in example sketch	IMU
Description	This function can be used to read angular velocity from the on-board IMU on a specific axis. The parameters are addresses to float variables for each axis. The angular velocity is returned in units mrad/s.

readGyroZ

Function	float readGyroZ()
Return Type	`float`
Return Value	Returns angular velocity on Z-axis in units of mrad/s.
Used in example sketch	IMU
Description	This function can be used to read angular velocity from the on-board IMU on a specific axis. The parameters are addresses to float variables for each axis. The angular velocity is returned in units mrad/s.

Barometer Functions

readPressure

Function	float readPressure()
Return Type	`float`
Return Value	Pressure in mbar
Parameters	None
Used in example sketch	Baro
Description	This function returns pressure as reported by the on-board barometer. The pressure is in units of millibar.

readTemperature

Function	float readTemperature()
Return Type	`float`
Return Value	Temperature in Celsius
Parameters	None
Used in example sketch	Baro
Description	This function returns temperature as reported by the on-board barometer. The unit of the reading is Celsius. Note that this is the internal temperature measured by the barometer, so it might not reflect the external temperature.

SD Card / File System Functions

SDCardPresent

Function	bool SDCardPresent()
Return Type	`bool`
Return Value	Returns true if it detects an SD-card, false if not.
Parameters	None
Used in example sketch	SD_advanced
Description	This function can be used to check if the SD-card is mechanically present. The SD-card connector has a mechanical switch, which is read when this function is called. Returns true or false depending on whether the SD-card is detected.

appendFile

Function	uint8_t appendFile(String filename, T data)
Return Type	`uint8_t`
Return Value	Returns 0 if write was successful.
Parameters
	`String filename`: Address of the file to be appended. If the file doesn’t exist, it is created.
	`T data`: Data to be appended at the end of the file.
Used in example sketch	SD_write
Description	This is the basic write function used to store readings to the SD-card.

printFileSystem

Function	void printFileSystem()
Return Type	`void`
Parameters	None
Used in example sketch	SD_advanced
Description	This is a small helper function to print names of files and folders present on the SD-card. Can be used in development.

newDir

Function	void newDir(String path)
Return Type	`void`
Parameters
	`String path`: Path of the new directory. If it already exists, nothing is done.
Used in example sketch	SD_advanced
Description	Used to create new directories on the SD-card.

deleteDir

Function	void deleteDir(String path)
Return Type	`void`
Parameters
	`String path`: Path of the directory to be deleted.
Used in example sketch	SD_advanced
Description	Used to delete directories on the SD-card.

fileExists

Function	bool fileExists(String path)
Return Type	`bool`
Return Value	Returns true if the file exists.
Parameters
	`String path`: Path to the file.
Used in example sketch	SD_advanced
Description	This function can be used to check if a file exists on the SD-card.

fileSize

Function	uint32_t fileSize(String path)
Return Type	`uint32_t`
Return Value	Size of the file in bytes.
Parameters
	`String path`: Path to the file.
Used in example sketch	SD_advanced
Description	This function can be used to read the size of a file on the SD-card.

writeFile

Function	uint8_t writeFile(String filename, T data)
Return Type	`uint8_t`
Return Value	Returns 0 if write was successful.
Parameters
	`String filename`: Address of the file to be written.
	`T data`: Data to be written to the file.
Used in example sketch	SD_advanced
Description	This function is similar to the `appendFile()`, but it overwrites existing data on the SD-card. For data storage, `appendFile` should be used instead. This function can be useful for storing settings, for example.

readFile

Function	String readFile(String path)
Return Type	`String`
Return Value	All content in the file.
Parameters
	`String path`: Path to the file.
Used in example sketch	SD_advanced
Description	This function can be used to read all data from a file into a variable. Attempting to read large files can cause problems, but it is fine for small files, such as configuration or setting files.

renameFile

Function	void renameFile(String oldpath, String newpath)
Return Type	`void`
Parameters
	`String oldpath`: Original path to the file.
	`String newpath`: New path of the file.
Used in example sketch	SD_advanced
Description	This function can be used to rename or move files on the SD-card.

deleteFile

Function	void deleteFile(String path)
Return Type	`void`
Parameters
	`String path`: Path of the file to be deleted.
Used in example sketch	SD_advanced
Description	This function can be used to delete files from the SD-card.

Radio Functions

onDataReceived

Function	void onDataReceived(String data)
Return Type	`void`
Parameters
	`String data`: Received data as an Arduino String.
Used in example sketch	Groundstation_receive
Description	This is a callback function that is called when data is received. The user code should define this function, and the CanSat NeXT will call it automatically when data is received.

onBinaryDataReceived

Function	void onBinaryDataReceived(const uint8_t *data, int len)
Return Type	`void`
Parameters
	`const uint8_t *data`: Received data as a uint8_t array.
	`int len`: Length of received data in bytes.
Used in example sketch	None
Description	This is similar to the `onDataReceived` function, but the data is provided as binary instead of a String object. This is provided for advanced users who find the String object limiting.

onDataSent

Function	void onDataSent(const bool success)
Return Type	`void`
Parameters
	`const bool success`: Boolean indicating if data was sent successfully.
Used in example sketch	None
Description	This is another callback function that can be added to the user code if required. It can be used to check if the reception was acknowledged by another radio.

sendData (String variant)

Function	uint8_t sendData(T data)
Return Type	`uint8_t`
Return Value	0 if data was sent (does not indicate acknowledgment).
Parameters
	`T data`: Data to be sent. Any type of data can be used, but is converted to a string internally.
Used in example sketch	Send_data
Description	This is the main function for sending data between the ground station and the satellite. Note that the return value does not indicate if data was actually received, just that it was sent. The callback `onDataSent` can be used to check if the data was received by the other end.

sendData (Binary variant)

Function	uint8_t sendData(char *data, uint16_t len)
Return Type	`uint8_t`
Return Value	0 if data was sent (does not indicate acknowledgment).
Parameters
	`char *data`: Data to be sent as a char array.
	`uint16_t len`: Length of the data in bytes.
Used in example sketch	None
Description	A binary variant of the `sendData` function, provided for advanced users who feel limited by the String object.

ADC Functions

adcToVoltage

Function	float adcToVoltage(int value)
Return Type	`float`
Return Value	Converted voltage as volts.
Parameters
	`int value`: ADC reading to be converted to voltage.
Used in example sketch	AccurateAnalogRead
Description	This function converts an ADC reading to voltage using a calibrated third-order polynomial for more linear conversion. Note that this function calculates the voltage at the input pin, so to calculate the battery voltage, you need to also consider the resistor network.

analogReadVoltage

Function	float analogReadVoltage(int pin)
Return Type	`float`
Return Value	ADC voltage as volts.
Parameters
	`int pin`: Pin to be read.
Used in example sketch	AccurateAnalogRead
Description	This function reads voltage directly instead of using `analogRead` and converts the reading to voltage internally using `adcToVoltage`.

Library specification

Functions

System Initialization Functions​

CanSatInit​

CanSatInit (simplified MAC-address specification)​

GroundStationInit​

GroundStationInit (simplified MAC-address specification)​

IMU Functions​

readAcceleration​

readAccelX​

readAccelY​

readAccelZ​

readGyro​

readGyroX​

readGyroY​

readGyroZ​

Barometer Functions​

readPressure​

readTemperature​

SD Card / File System Functions​

SDCardPresent​

appendFile​

printFileSystem​

newDir​

deleteDir​

fileExists​

fileSize​

writeFile​

readFile​

renameFile​

deleteFile​

Radio Functions​

onDataReceived​

onBinaryDataReceived​

onDataSent​

sendData (String variant)​

sendData (Binary variant)​

ADC Functions​

adcToVoltage​

analogReadVoltage​