diff --git a/src/SparkFun_Toolkit.h b/src/SparkFun_Toolkit.h index aee8e9f..b2c293b 100644 --- a/src/SparkFun_Toolkit.h +++ b/src/SparkFun_Toolkit.h @@ -1,27 +1,15 @@ - -/* -SparkFun_Toolkit.h - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ +/** + * @file SparkFun_Toolkit.h + * @brief Arduino style header file for the SparkFun Toolkit + * + * This file contains the Arduino style header for the SparkFun Toolkit library + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ #pragma once @@ -31,6 +19,6 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. // Arduino Libraries. // Just include the toolkit headers -#include "sfeTkArdI2C.h" -#include "sfeTkArdSPI.h" -#include "sfeTkArduino.h" +#include "sfTkArdI2C.h" +#include "sfTkArdSPI.h" +#include "sfTkArduino.h" diff --git a/src/sfTk/sfTkError.h b/src/sfTk/sfTkError.h new file mode 100644 index 0000000..c4e4632 --- /dev/null +++ b/src/sfTk/sfTkError.h @@ -0,0 +1,52 @@ + /** + * @file sfTkError.h + * @brief Header file for the SparkFun Toolkit - Base Error Code defines. + * + * This file contains the base error code definitions for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + + +#pragma once + +#include + +/** + * General Concept + * A SparkFun Toolkit error system. The goal is to keep this simple. + * + * This mimics a variety of systems, using an int type for error codes, + * where: + * 0 = okay + * -1 = general failure + * >0 = an informative error + * + * Since *subsystems* in the toolkit can have their own errors, + * A start range for these errors are defined. Values > than this value + * define the errors for the set subsystem. These start ranges are set + * in this file, with actual error values defined in the the respective + * subsystem header files. + * + */ +typedef int32_t sfTkError_t; + +// General errors + +/** + * @brief General error code for a failure. Note all errors are negative. + */ +const sfTkError_t ksfTkErrFail = -1; // general fail +/** + * @brief The error code value for success. This is always 0. + */ +const sfTkError_t ksfTkErrOk = 0; // success + +/** + * @brief A base value for bus errors. All bus errors are greater than this value, in the 1000 range + */ +const sfTkError_t ksfTkErrBaseBus = 0x1000; diff --git a/src/sfeTk/sfeTkIBus.h b/src/sfTk/sfTkIBus.h similarity index 58% rename from src/sfeTk/sfeTkIBus.h rename to src/sfTk/sfTkIBus.h index 43479e8..16bc09e 100644 --- a/src/sfeTk/sfeTkIBus.h +++ b/src/sfTk/sfTkIBus.h @@ -1,33 +1,19 @@ - -// sfeTkIBus.h -// -// Defines the communication bus interface for the SparkFun Electronics Toolkit -> sfeTk -/* - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ +/** + * @file sfTkIBus.h + * @brief Header file for the SparkFun Toolkit Device Bus Interface Definition. + * + * This file contains the interface declaration for the Communication Bus Interface + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ #pragma once -#include "sfeToolkit.h" +#include "sfToolkit.h" #include /** @@ -39,42 +25,42 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. /** * @brief Error code for when a bus system is not initalized. */ -const sfeTkError_t kSTkErrBusNotInit = kSTkErrFail * (kSTkErrBaseBus + 1); +const sfTkError_t ksfTkErrBusNotInit = ksfTkErrFail * (ksfTkErrBaseBus + 1); /** * @brief Returned when a bus system times out. */ -const sfeTkError_t kSTkErrBusTimeout = kSTkErrFail * (kSTkErrBaseBus + 2); +const sfTkError_t ksfTkErrBusTimeout = ksfTkErrFail * (ksfTkErrBaseBus + 2); /** * @brief Returned when a bus system does not respond. */ -const sfeTkError_t kSTkErrBusNoResponse = kSTkErrFail * (kSTkErrBaseBus + 3); +const sfTkError_t ksfTkErrBusNoResponse = ksfTkErrFail * (ksfTkErrBaseBus + 3); /** * @brief Returned when the data to be sent is too long or received is too short. */ -const sfeTkError_t kSTkErrBusDataTooLong = kSTkErrFail * (kSTkErrBaseBus + 4); +const sfTkError_t ksfTkErrBusDataTooLong = ksfTkErrFail * (ksfTkErrBaseBus + 4); /** * @brief Returned when the bus settings are null, invalid or on set/initialised */ -const sfeTkError_t kSTkErrBusNullSettings = kSTkErrFail * (kSTkErrBaseBus + 5); +const sfTkError_t ksfTkErrBusNullSettings = ksfTkErrFail * (ksfTkErrBaseBus + 5); /** * @brief Returned when the buffer is null or invalid. */ -const sfeTkError_t kSTkErrBusNullBuffer = kSTkErrFail * (kSTkErrBaseBus + 6); +const sfTkError_t ksfTkErrBusNullBuffer = ksfTkErrFail * (ksfTkErrBaseBus + 6); /** * @brief Returned when the bus is under read. Warning */ -const sfeTkError_t kSTkErrBusUnderRead = kSTkErrBaseBus + 7; +const sfTkError_t ksfTkErrBusUnderRead = ksfTkErrBaseBus + 7; /** * @brief Returned when the bus is not enabled. Warning */ -const sfeTkError_t kSTkErrBusNotEnabled = kSTkErrBaseBus + 8; +const sfTkError_t ksfTkErrBusNotEnabled = ksfTkErrBaseBus + 8; /** * @brief Interface that defines the communication bus for the SparkFun Electronics Toolkit. @@ -83,42 +69,42 @@ const sfeTkError_t kSTkErrBusNotEnabled = kSTkErrBaseBus + 8; * bus implementations will extend this interface to provide the necessary functionality for the * desired bus type. */ -class sfeTkIBus +class sfTkIBus { public: /** * @brief Constructor */ - sfeTkIBus() { + sfTkIBus() { _byteOrder = sftk_system_byteorder(); } /**-------------------------------------------------------------------------- * @brief Send a single byte to the device* * @param data Data to write. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t writeByte(uint8_t data) = 0; + virtual sfTkError_t writeByte(uint8_t data) = 0; /**-------------------------------------------------------------------------- * @brief Send a word to the device. * @param data Data to write. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t writeWord(uint16_t data) = 0; + virtual sfTkError_t writeWord(uint16_t data) = 0; /**-------------------------------------------------------------------------- * @brief Send an array of data to the device. * @param data Data to write. * @param length - length of data. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t writeRegion(const uint8_t *data, size_t length) = 0; + virtual sfTkError_t writeRegion(const uint8_t *data, size_t length) = 0; /**-------------------------------------------------------------------------- * @brief Write a single byte to the given register @@ -126,13 +112,13 @@ class sfeTkIBus * @param devReg The device's register's address. * @param data Data to write. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t writeRegisterByte(uint8_t devReg, uint8_t data) = 0; + virtual sfTkError_t writeRegisterByte(uint8_t devReg, uint8_t data) = 0; // Overload version - sfeTkError_t writeRegister(uint8_t devReg, uint8_t data) + sfTkError_t writeRegister(uint8_t devReg, uint8_t data) { return writeRegisterByte(devReg, data); } @@ -143,13 +129,13 @@ class sfeTkIBus * @param devReg The device's register's address. * @param data Data to write. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t writeRegisterWord(uint8_t devReg, uint16_t data) = 0; + virtual sfTkError_t writeRegisterWord(uint8_t devReg, uint16_t data) = 0; // Overload version - sfeTkError_t writeRegister(uint8_t devReg, uint16_t data) + sfTkError_t writeRegister(uint8_t devReg, uint16_t data) { return writeRegisterWord(devReg, data); } @@ -161,13 +147,13 @@ class sfeTkIBus * @param data Data to write. * @param length - length of data * - * @retval sfeTkError_t kSTkErrOk on successful execution + * @retval sfTkError_t ksfTkErrOk on successful execution * */ - virtual sfeTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) = 0; + virtual sfTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) = 0; // Overload version - sfeTkError_t writeRegister(uint8_t devReg, const uint8_t *data, size_t length) + sfTkError_t writeRegister(uint8_t devReg, const uint8_t *data, size_t length) { return writeRegisterRegion(devReg, data, length); } @@ -179,13 +165,13 @@ class sfeTkIBus * @param data Data to write. * @param length - length of data * - * @retval sfeTkError_t kSTkErrOk on successful execution + * @retval sfTkError_t ksfTkErrOk on successful execution * */ - virtual sfeTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) = 0; + virtual sfTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) = 0; // Overload version - sfeTkError_t writeRegister(uint16_t devReg, const uint8_t *data, size_t length) + sfTkError_t writeRegister(uint16_t devReg, const uint8_t *data, size_t length) { return writeRegister16Region(devReg, data, length); } @@ -197,13 +183,13 @@ class sfeTkIBus * @param data Data to write. * @param length - length of data * - * @retval sfeTkError_t kSTkErrOk on successful execution + * @retval sfTkError_t ksfTkErrOk on successful execution * */ - virtual sfeTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) = 0; + virtual sfTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) = 0; // Overload version - sfeTkError_t writeRegister(uint16_t devReg, const uint16_t *data, size_t length) + sfTkError_t writeRegister(uint16_t devReg, const uint16_t *data, size_t length) { return writeRegister16Region16(devReg, data, length); } @@ -213,13 +199,13 @@ class sfeTkIBus * @param devReg The device's register's address. * @param data Data to read. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. * */ - virtual sfeTkError_t readRegisterByte(uint8_t devReg, uint8_t &data) = 0; + virtual sfTkError_t readRegisterByte(uint8_t devReg, uint8_t &data) = 0; // Overload version - sfeTkError_t readRegister(uint8_t devReg, uint8_t &data) + sfTkError_t readRegister(uint8_t devReg, uint8_t &data) { return readRegisterByte(devReg, data); } @@ -230,12 +216,12 @@ class sfeTkIBus * @param devReg The device's register's address. * @param data Data to read. * - * @retval sfeTkError_t - kSTkErrOk on successful execution. + * @retval sfTkError_t - ksfTkErrOk on successful execution. */ - virtual sfeTkError_t readRegisterWord(uint8_t devReg, uint16_t &data) = 0; + virtual sfTkError_t readRegisterWord(uint8_t devReg, uint16_t &data) = 0; // Overload version - sfeTkError_t readRegister(uint8_t devReg, uint16_t &data) + sfTkError_t readRegister(uint8_t devReg, uint16_t &data) { return readRegisterWord(devReg, data); } @@ -248,13 +234,13 @@ class sfeTkIBus * @param numBytes - length of data * @param[out] readBytes - number of bytes read * - * @retval int returns kSTkErrOk on success, or kSTkErrFail code + * @retval int returns ksfTkErrOk on success, or ksfTkErrFail code * */ - virtual sfeTkError_t readRegisterRegion(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0; + virtual sfTkError_t readRegisterRegion(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0; // Overload version - sfeTkError_t readRegister(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) + sfTkError_t readRegister(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) { return readRegisterRegion(reg, data, numBytes, readBytes); } @@ -267,13 +253,13 @@ class sfeTkIBus * @param numBytes - length of data * @param[out] readBytes - number of bytes read * - * @retval int returns kSTkErrOk on success, or kSTkErrFail code + * @retval int returns ksfTkErrOk on success, or ksfTkErrFail code * */ - virtual sfeTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0; + virtual sfTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) = 0; // Overload version - sfeTkError_t readRegister(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) + sfTkError_t readRegister(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes) { return readRegister16Region(reg, data, numBytes, readBytes); } @@ -285,13 +271,13 @@ class sfeTkIBus * @param numBytes - length of data * @param[out] readBytes - number of bytes read * - * @retval int returns kSTkErrOk on success, or kSTkErrFail code + * @retval int returns ksfTkErrOk on success, or ksfTkErrFail code * */ - virtual sfeTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes) = 0; + virtual sfTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes) = 0; // Overload version - sfeTkError_t readRegister(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes) + sfTkError_t readRegister(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes) { return readRegister16Region16(reg, data, numBytes, readBytes); } @@ -306,7 +292,7 @@ class sfeTkIBus * @param order The byte order to set - set to either SFTK_MSBFIRST or SFTK_LSBFIRST. The default is SFTK_LSBFIRST * */ - void setByteOrder(sfeTKByteOrder order) + void setByteOrder(sfTkByteOrder order) { _byteOrder = order; } @@ -316,13 +302,13 @@ class sfeTkIBus * * @retval The current byte order */ - sfeTKByteOrder byteOrder(void) + sfTkByteOrder byteOrder(void) { return _byteOrder; } protected: /** flag to manage byte swapping */ - sfeTKByteOrder _byteOrder; + sfTkByteOrder _byteOrder; }; diff --git a/src/sfeTk/sfeTkII2C.h b/src/sfTk/sfTkII2C.h similarity index 56% rename from src/sfeTk/sfeTkII2C.h rename to src/sfTk/sfTkII2C.h index 264d243..2ecc379 100644 --- a/src/sfeTk/sfeTkII2C.h +++ b/src/sfTk/sfTkII2C.h @@ -1,32 +1,19 @@ - -// sfeTkII2C.h -// -// Defines the I2C communication bus interface for the SparkFun Electronics Toolkit -/* -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ +/** + * @file sfTkII2C.h + * @brief Header file for the SparkFun Toolkit I2C Interface Definition. + * + * This file contains the interface declaration for the I2C communication bus + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ #pragma once -#include "sfeTkIBus.h" +#include "sfTkIBus.h" /** * @brief Interface that defines the I2C communication bus for the SparkFun Electronics Toolkit. @@ -34,16 +21,16 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * The I2C bus interface extends the IBus interface and adds the ability to set and get the I2C * address and stop flag. */ -const uint8_t kBusTypeI2C = 0x01; +const uint8_t ksfTkBusTypeI2C = 0x01; -class sfeTkII2C : public sfeTkIBus +class sfTkII2C : public sfTkIBus { public: // set the address to No address and stop flag to true /** * @brief Constructor for the I2C bus */ - sfeTkII2C() : _address{kNoAddress}, _stop{true} + sfTkII2C() : _address{kNoAddress}, _stop{true} { } /** @@ -51,17 +38,17 @@ class sfeTkII2C : public sfeTkIBus * * @param addr */ - sfeTkII2C(uint8_t addr) : _address{addr} + sfTkII2C(uint8_t addr) : _address{addr} { } /**-------------------------------------------------------------------------- @brief A simple ping of the device at the set address - @retval sfeTkError_t - ok on success + @retval sfTkError_t - ok on success */ - virtual sfeTkError_t ping() = 0; + virtual sfTkError_t ping() = 0; /**-------------------------------------------------------------------------- @brief setter for the I2C address @@ -113,7 +100,7 @@ class sfeTkII2C : public sfeTkIBus virtual uint8_t type(void) { - return kBusTypeI2C; + return ksfTkBusTypeI2C; } private: diff --git a/src/sfTk/sfTkISPI.h b/src/sfTk/sfTkISPI.h new file mode 100644 index 0000000..d063378 --- /dev/null +++ b/src/sfTk/sfTkISPI.h @@ -0,0 +1,83 @@ +/** + * @file sfTkISPI.h + * @brief Header file for the SparkFun Toolkit SPI Interface Definition. + * + * This file contains the interface declaration for the SPI communication bus + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + +#pragma once + +#include "sfTkIBus.h" + +/** + * @brief Interface that defines the SPI communication bus for the SparkFun Electronics Toolkit. + * + * The SPI bus interface extends the IBus interface and adds the ability to set and get the CS pin. + */ + +const uint8_t ksfTkBusTypeSPI = 0x02; +class sfTkISPI : public sfTkIBus +{ + public: + /**-------------------------------------------------------------------------- + @brief Constructor for the SPI bus + + */ + sfTkISPI() : _cs{kNoCSPin} + { + } + + /**-------------------------------------------------------------------------- + @brief Constructor for the SPI bus + + @param csPin The CS Pin for the device + + */ + sfTkISPI(uint8_t csPin) : _cs{csPin} + { + } + + /**-------------------------------------------------------------------------- + @brief setter for the CS Pin + + @param devCS The device's CS Pin + + */ + virtual void setCS(uint8_t devCS) + { + _cs = devCS; + } + + /**-------------------------------------------------------------------------- + @brief getter for the cs pin + + @retval uint8_t returns the CS pin for the device + + */ + virtual uint8_t cs(void) + { + return _cs; + } + + /**-------------------------------------------------------------------------- + @brief A constant for no CS pin + */ + static constexpr uint8_t kNoCSPin = 0; + + virtual uint8_t type(void) + { + return ksfTkBusTypeSPI; + } + + private: + /** The internal storage of the _cs value*/ + uint8_t _cs; +}; + +//}; diff --git a/src/sfeTk/sfeToolkit.cpp b/src/sfTk/sfToolkit.cpp similarity index 79% rename from src/sfeTk/sfeToolkit.cpp rename to src/sfTk/sfToolkit.cpp index 75cb3eb..593d46c 100644 --- a/src/sfeTk/sfeToolkit.cpp +++ b/src/sfTk/sfToolkit.cpp @@ -1,4 +1,18 @@ -// File: sfeToolkit.cpp +/** + * @file sfToolkit.cpp + * @brief Implementation file for the SparkFun Toolkit. + * + * This file contains the implementation of various utility functions + * for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + +// File: sfToolkit.cpp // // General impl file for the SparkFun Toolkit /* @@ -22,9 +36,9 @@ HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ -#include "sfeToolkit.h" +#include "sfToolkit.h" + -// THIS IS A PLACEHOLDER FILE for now #ifdef ARDUINO #include #endif @@ -32,10 +46,10 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. /** * @brief C function - Runtime check for system byte order */ -sfeTKByteOrder sftk_system_byteorder(void) +sfTkByteOrder sftk_system_byteorder(void) { uint16_t i = 1; - return *((uint8_t *)&i) == 0 ? sfeTKByteOrder::BigEndian : sfeTKByteOrder::LittleEndian; + return *((uint8_t *)&i) == 0 ? sfTkByteOrder::BigEndian : sfTkByteOrder::LittleEndian; } //--------------------------------------------------------------------------------- diff --git a/src/sfTk/sfToolkit.h b/src/sfTk/sfToolkit.h new file mode 100644 index 0000000..1295601 --- /dev/null +++ b/src/sfTk/sfToolkit.h @@ -0,0 +1,51 @@ + +/** + * @file sfToolkit.h + * @brief Header file for the SparkFun Toolkit. + * + * This file contains the declarations of various utility functions + * and types for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + + +#pragma once + +#include + +/** + @brief Common include file for the core of the SparkFun Electronics Toolkit +*/ +#include "sfTkError.h" + + +// byte order types/enum +enum class sfTkByteOrder : uint8_t +{ + BigEndian = 0x01, + LittleEndian = 0x02 +}; + +// Note - toolkit *functions* start with sftk_ to avoid name collisions + +// Function to determine the byte order of the system +sfTkByteOrder sftk_system_byteorder(void); + +uint8_t sftk_byte_swap(uint8_t i); +uint16_t sftk_byte_swap(uint16_t i); +uint32_t sftk_byte_swap(uint32_t i); + + +// Area for platform specific implementations. The interface/functions are +// defined here, with the expectation that the platform provides the implementation. + +// delay in milliseconds +void sftk_delay_ms(uint32_t ms); + +// ticks in milliseconds +uint32_t sftk_ticks_ms(void); \ No newline at end of file diff --git a/src/sfeTkArdI2C.cpp b/src/sfTkArdI2C.cpp similarity index 66% rename from src/sfeTkArdI2C.cpp rename to src/sfTkArdI2C.cpp index 3d8dbc3..216db72 100644 --- a/src/sfeTkArdI2C.cpp +++ b/src/sfTkArdI2C.cpp @@ -1,34 +1,25 @@ -/* -sfeTkArdI2C.cpp -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#include "sfeTkArdI2C.h" +/** + * @file sfTkArdI2C.h + * @brief Implementation file for the SparkFun Toolkit Arduino I2C driver. + * + * This file contains the Arduino I2C driver for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + + +#include "sfTkArdI2C.h" //--------------------------------------------------------------------------------- // init() // // Arduino version of init - pass in already setup wire port ... // -sfeTkError_t sfeTkArdI2C::init(TwoWire &wirePort, uint8_t addr, bool bInit) +sfTkError_t sfTkArdI2C::init(TwoWire &wirePort, uint8_t addr, bool bInit) { // if we don't have a wire port already if (!_i2cPort) @@ -41,7 +32,7 @@ sfeTkError_t sfeTkArdI2C::init(TwoWire &wirePort, uint8_t addr, bool bInit) } setAddress(addr); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -49,14 +40,14 @@ sfeTkError_t sfeTkArdI2C::init(TwoWire &wirePort, uint8_t addr, bool bInit) // // no parameters version of init. Setups a a wire port if needed. // -sfeTkError_t sfeTkArdI2C::init(uint8_t addr) +sfTkError_t sfTkArdI2C::init(uint8_t addr) { // no port yet, do the default version of it if (!_i2cPort) return init(Wire, addr); // We have a port, so arcady init'd - right? - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -64,7 +55,7 @@ sfeTkError_t sfeTkArdI2C::init(uint8_t addr) // // no parameters version of init. Setups a a wire port if needed. // -sfeTkError_t sfeTkArdI2C::init(void) +sfTkError_t sfTkArdI2C::init(void) { // call with our currently set address ... return init(address()); @@ -74,14 +65,14 @@ sfeTkError_t sfeTkArdI2C::init(void) // // Ping an I2C address to see if something is there. // -sfeTkError_t sfeTkArdI2C::ping() +sfTkError_t sfTkArdI2C::ping() { // no port, no if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; _i2cPort->beginTransmission(address()); - return _i2cPort->endTransmission() == 0 ? kSTkErrOk : kSTkErrFail; + return _i2cPort->endTransmission() == 0 ? ksfTkErrOk : ksfTkErrFail; } //--------------------------------------------------------------------------------- @@ -91,15 +82,15 @@ sfeTkError_t sfeTkArdI2C::ping() // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::writeByte(uint8_t dataToWrite) +sfTkError_t sfTkArdI2C::writeByte(uint8_t dataToWrite) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // do the Arduino I2C work _i2cPort->beginTransmission(address()); _i2cPort->write(dataToWrite); - return _i2cPort->endTransmission() == 0 ? kSTkErrOk : kSTkErrFail; + return _i2cPort->endTransmission() == 0 ? ksfTkErrOk : ksfTkErrFail; } //--------------------------------------------------------------------------------- @@ -109,10 +100,10 @@ sfeTkError_t sfeTkArdI2C::writeByte(uint8_t dataToWrite) // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::writeWord(uint16_t dataToWrite) +sfTkError_t sfTkArdI2C::writeWord(uint16_t dataToWrite) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; return writeRegion((uint8_t *)&dataToWrite, sizeof(uint16_t)); } @@ -124,9 +115,9 @@ sfeTkError_t sfeTkArdI2C::writeWord(uint16_t dataToWrite) // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::writeRegion(const uint8_t *data, size_t length) +sfTkError_t sfTkArdI2C::writeRegion(const uint8_t *data, size_t length) { - return writeRegisterRegionAddress(nullptr, 0, data, length) == 0 ? kSTkErrOk : kSTkErrFail; + return writeRegisterRegionAddress(nullptr, 0, data, length) == 0 ? ksfTkErrOk : ksfTkErrFail; } //--------------------------------------------------------------------------------- @@ -136,16 +127,16 @@ sfeTkError_t sfeTkArdI2C::writeRegion(const uint8_t *data, size_t length) // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) +sfTkError_t sfTkArdI2C::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // do the Arduino I2C work _i2cPort->beginTransmission(address()); _i2cPort->write(devReg); _i2cPort->write(dataToWrite); - return _i2cPort->endTransmission() == 0 ? kSTkErrOk : kSTkErrFail; + return _i2cPort->endTransmission() == 0 ? ksfTkErrOk : ksfTkErrFail; } //--------------------------------------------------------------------------------- @@ -155,10 +146,10 @@ sfeTkError_t sfeTkArdI2C::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite) +sfTkError_t sfTkArdI2C::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; return writeRegisterRegion(devReg, (uint8_t *)&dataToWrite, sizeof(uint16_t)); } @@ -170,13 +161,13 @@ sfeTkError_t sfeTkArdI2C::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite * @param regLength The length of the register address * @param data The data to write * @param length The length of the data buffer - * @return sfeTkError_t Returns kSTkErrOk on success, or kSTkErrFail code + * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code */ -sfeTkError_t sfeTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t regLength, const uint8_t *data, - size_t length) +sfTkError_t sfTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t regLength, const uint8_t *data, + size_t length) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; _i2cPort->beginTransmission(address()); @@ -185,7 +176,7 @@ sfeTkError_t sfeTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t reg _i2cPort->write(data, (int)length); - return _i2cPort->endTransmission() ? kSTkErrFail : kSTkErrOk; + return _i2cPort->endTransmission() ? ksfTkErrFail : ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -195,7 +186,7 @@ sfeTkError_t sfeTkArdI2C::writeRegisterRegionAddress(uint8_t *devReg, size_t reg // // Returns the number of bytes written, < 0 is an error // -sfeTkError_t sfeTkArdI2C::writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) +sfTkError_t sfTkArdI2C::writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) { return writeRegisterRegionAddress(&devReg, 1, data, length); } @@ -207,7 +198,7 @@ sfeTkError_t sfeTkArdI2C::writeRegisterRegion(uint8_t devReg, const uint8_t *dat // // Returns the number of bytes written, < 0 is an error // -sfeTkError_t sfeTkArdI2C::writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) +sfTkError_t sfTkArdI2C::writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) { // Byteorder check if (sftk_system_byteorder() != _byteOrder) @@ -222,7 +213,7 @@ sfeTkError_t sfeTkArdI2C::writeRegister16Region(uint16_t devReg, const uint8_t * // // Returns the number of bytes written, < 0 is an error // -sfeTkError_t sfeTkArdI2C::writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) +sfTkError_t sfTkArdI2C::writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) { // if the system byte order is the same as the desired order, just send the buffer if (sftk_system_byteorder() == _byteOrder) @@ -230,10 +221,10 @@ sfeTkError_t sfeTkArdI2C::writeRegister16Region16(uint16_t devReg, const uint16_ // okay, we need to swap devReg = sftk_byte_swap(devReg); - + uint16_t data16[length]; for (size_t i = 0; i < length; i++) - data16[i] = ((data[i] << 8) & 0xff00) | ((data[i] >> 8) & 0x00ff); + data16[i] = sftk_byte_swap(data[i]); return writeRegisterRegionAddress((uint8_t *)&devReg, 2, (uint8_t *)data16, length * 2); } @@ -246,19 +237,19 @@ sfeTkError_t sfeTkArdI2C::writeRegister16Region16(uint16_t devReg, const uint16_ * @param data The data to buffer to read into * @param numBytes The length of the data buffer * @param readBytes[out] The number of bytes read - * @return sfeTkError_t Returns kSTkErrOk on success, or kSTkErrFail code + * @return sfTkError_t Returns ksfTkErrOk on success, or ksfTkErrFail code */ -sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t regLength, uint8_t *data, - size_t numBytes, size_t &readBytes) +sfTkError_t sfTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t regLength, uint8_t *data, size_t numBytes, + size_t &readBytes) { // got port if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Buffer valid? if (!data) - return kSTkErrBusNullBuffer; + return ksfTkErrBusNullBuffer; readBytes = 0; @@ -277,7 +268,7 @@ sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t r _i2cPort->write(devReg, regLength); if (_i2cPort->endTransmission(stop()) != 0) - return kSTkErrFail; // error with the end transmission + return ksfTkErrFail; // error with the end transmission bFirstInter = false; } @@ -290,7 +281,7 @@ sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t r // No data returned, no dice if (nReturned == 0) - return kSTkErrBusUnderRead; // error + return ksfTkErrBusUnderRead; // error // Copy the retrieved data chunk to the current index in the data segment for (i = 0; i < nReturned; i++) @@ -303,7 +294,7 @@ sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t r readBytes = nOrig - numBytes; // Bytes read. - return (readBytes == nOrig) ? kSTkErrOk : kSTkErrBusUnderRead; // Success + return (readBytes == nOrig) ? ksfTkErrOk : ksfTkErrBusUnderRead; // Success } //--------------------------------------------------------------------------------- @@ -313,10 +304,10 @@ sfeTkError_t sfeTkArdI2C::readRegisterRegionAnyAddress(uint8_t *devReg, size_t r // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::readRegisterByte(uint8_t devReg, uint8_t &dataToRead) +sfTkError_t sfTkArdI2C::readRegisterByte(uint8_t devReg, uint8_t &dataToRead) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Return value uint8_t result = 0; @@ -337,7 +328,7 @@ sfeTkError_t sfeTkArdI2C::readRegisterByte(uint8_t devReg, uint8_t &dataToRead) if (nData == sizeof(uint8_t)) // Only update outputPointer if a single byte was returned dataToRead = result; - return (nData == sizeof(uint8_t) ? kSTkErrOk : kSTkErrFail); + return (nData == sizeof(uint8_t) ? ksfTkErrOk : ksfTkErrFail); } //--------------------------------------------------------------------------------- @@ -347,15 +338,15 @@ sfeTkError_t sfeTkArdI2C::readRegisterByte(uint8_t devReg, uint8_t &dataToRead) // // Returns true on success, false on failure // -sfeTkError_t sfeTkArdI2C::readRegisterWord(uint8_t devReg, uint16_t &dataToRead) +sfTkError_t sfTkArdI2C::readRegisterWord(uint8_t devReg, uint16_t &dataToRead) { if (!_i2cPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; size_t nRead; - sfeTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&dataToRead, sizeof(uint16_t), nRead); + sfTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&dataToRead, sizeof(uint16_t), nRead); - return (retval == kSTkErrOk && nRead == sizeof(uint16_t) ? kSTkErrOk : retval); + return (retval == ksfTkErrOk && nRead == sizeof(uint16_t) ? ksfTkErrOk : retval); } //--------------------------------------------------------------------------------- @@ -365,7 +356,7 @@ sfeTkError_t sfeTkArdI2C::readRegisterWord(uint8_t devReg, uint16_t &dataToRead) // // Returns the number of bytes read, < 0 is an error // -sfeTkError_t sfeTkArdI2C::readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) +sfTkError_t sfTkArdI2C::readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) { return readRegisterRegionAnyAddress(&devReg, 1, data, numBytes, readBytes); } @@ -377,9 +368,12 @@ sfeTkError_t sfeTkArdI2C::readRegisterRegion(uint8_t devReg, uint8_t *data, size // // Returns the number of bytes read, < 0 is an error // -sfeTkError_t sfeTkArdI2C::readRegister16Region(uint16_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) +sfTkError_t sfTkArdI2C::readRegister16Region(uint16_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) { - devReg = ((devReg << 8) & 0xff00) | ((devReg >> 8) & 0x00ff); + // if the system byte order is the same as the desired order, flip the address + if (sftk_system_byteorder() != _byteOrder) + devReg = sftk_byte_swap(devReg); + return readRegisterRegionAnyAddress((uint8_t *)&devReg, 2, data, numBytes, readBytes); } //--------------------------------------------------------------------------------- @@ -389,17 +383,16 @@ sfeTkError_t sfeTkArdI2C::readRegister16Region(uint16_t devReg, uint8_t *data, s // // Returns the number of bytes read, < 0 is an error // -sfeTkError_t sfeTkArdI2C::readRegister16Region16(uint16_t devReg, uint16_t *data, size_t numBytes, size_t &readWords) +sfTkError_t sfTkArdI2C::readRegister16Region16(uint16_t devReg, uint16_t *data, size_t numBytes, size_t &readWords) { // if the system byte order is the same as the desired order, flip the address if (sftk_system_byteorder() != _byteOrder) devReg = sftk_byte_swap(devReg); - - sfeTkError_t status = readRegisterRegionAnyAddress((uint8_t *)&devReg, 2, (uint8_t *)data, numBytes * 2, readWords); + sfTkError_t status = readRegisterRegionAnyAddress((uint8_t *)&devReg, 2, (uint8_t *)data, numBytes * 2, readWords); // Do we need to flip the byte order? - if (status == kSTkErrOk && sftk_system_byteorder() != _byteOrder) + if (status == ksfTkErrOk && sftk_system_byteorder() != _byteOrder) { for (size_t i = 0; i < numBytes; i++) data[i] = sftk_byte_swap(data[i]); diff --git a/src/sfeTkArdI2C.h b/src/sfTkArdI2C.h similarity index 54% rename from src/sfeTkArdI2C.h rename to src/sfTkArdI2C.h index ac94991..9eb0e6b 100644 --- a/src/sfeTkArdI2C.h +++ b/src/sfTkArdI2C.h @@ -1,29 +1,15 @@ -/* -sfeTkArdI2c.h - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -The following classes specify the behavior for communicating -over Inter-Integrated Circuit (I2C) in Arduino - -*/ +/** + * @file sfTkArdI2C.cpp + * @brief header file for the SparkFun Toolkit Arduino I2C driver. + * + * This file contains the Arduino I2C header for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ #pragma once @@ -31,21 +17,21 @@ over Inter-Integrated Circuit (I2C) in Arduino #include // Include our platform I2C interface definition. -#include "sfeTkArduino.h" -#include +#include "sfTkArduino.h" +#include /** - * @brief The sfeTkArdI2C implements an sfeTkII2C interface, defining the Arduino implementation for I2C in the Toolkit + * @brief The sfTkArdI2C implements an sfTkII2C interface, defining the Arduino implementation for I2C in the Toolkit */ -class sfeTkArdI2C : public sfeTkII2C +class sfTkArdI2C : public sfTkII2C { public: /** @brief Constructor */ - sfeTkArdI2C(void) : _i2cPort(nullptr), _bufferChunkSize{kDefaultBufferChunk} + sfTkArdI2C(void) : _i2cPort(nullptr), _bufferChunkSize{kDefaultBufferChunk} { } /** @@ -53,14 +39,14 @@ class sfeTkArdI2C : public sfeTkII2C @param addr The address of the device */ - sfeTkArdI2C(uint8_t addr) : sfeTkII2C(addr) + sfTkArdI2C(uint8_t addr) : sfTkII2C(addr) { } /** * @brief copy constructor */ - sfeTkArdI2C(sfeTkArdI2C const &rhs) : sfeTkII2C(), _i2cPort{rhs._i2cPort} + sfTkArdI2C(sfTkArdI2C const &rhs) : sfTkII2C(), _i2cPort{rhs._i2cPort} { } @@ -70,7 +56,7 @@ class sfeTkArdI2C : public sfeTkII2C * @param rhs right hand side of the assignment * @return value of the left hand side of the assignment */ - sfeTkArdI2C &operator=(const sfeTkArdI2C &rhs) + sfTkArdI2C &operator=(const sfTkArdI2C &rhs) { _i2cPort = rhs._i2cPort; return *this; @@ -80,16 +66,16 @@ class sfeTkArdI2C : public sfeTkII2C @brief Method sets up the required I2C settings. @note This function provides a default I2C Port. - @retval kSTkErrOk on successful execution. + @retval ksfTkErrOk on successful execution. */ - sfeTkError_t init(); + sfTkError_t init(); /** @brief - address version of the init method @param addr The address of the device */ - sfeTkError_t init(uint8_t addr); + sfTkError_t init(uint8_t addr); /** @brief Method sets up the required I2C settings. @@ -98,84 +84,84 @@ class sfeTkArdI2C : public sfeTkII2C @param addr The address of the device @param bInit This flag tracks whether the bus has been initialized. - @retval kSTkErrOk on successful execution. + @retval ksfTkErrOk on successful execution. */ - sfeTkError_t init(TwoWire &wirePort, uint8_t addr, bool bInit = false); + sfTkError_t init(TwoWire &wirePort, uint8_t addr, bool bInit = false); /** @brief A simple ping of the device at the given address. - @note sfeTkIBus interface method + @note sfTkIBus interface method - @retval kSTkErrOk on success, + @retval ksfTkErrOk on success, */ - sfeTkError_t ping(); + sfTkError_t ping(); /** @brief Sends a single byte to the device - @note sfeTkIBus interface method + @note sfTkIBus interface method @param data Data to write. - @retval returns kStkErrOk on success + @retval returns ksfTkErrOk on success */ - sfeTkError_t writeByte(uint8_t data); + sfTkError_t writeByte(uint8_t data); /** @brief Sends a word to the device. - @note sfeTkIBus interface method + @note sfTkIBus interface method @param data Data to write. - @retval returns kStkErrOk on success + @retval returns ksfTkErrOk on success */ - sfeTkError_t writeWord(uint16_t data); + sfTkError_t writeWord(uint16_t data); /** @brief Sends a block of data to the device. - @note sfeTkIBus interface method + @note sfTkIBus interface method @param data Data to write. @param length - length of data - @retval returns kStkErrOk on success + @retval returns ksfTkErrOk on success */ - sfeTkError_t writeRegion(const uint8_t *data, size_t length); + sfTkError_t writeRegion(const uint8_t *data, size_t length); /** @brief Write a single byte to the given register - @note sfeTkIBus interface method + @note sfTkIBus interface method @param devReg The device's register's address. @param data Data to write. - @retval returns kStkErrOk on success + @retval returns ksfTkErrOk on success */ - sfeTkError_t writeRegisterByte(uint8_t devReg, uint8_t data); + sfTkError_t writeRegisterByte(uint8_t devReg, uint8_t data); /** @brief Write a single word to the given register - @note sfeTkIBus interface method + @note sfTkIBus interface method @param devReg The device's register's address. @param data Data to write. - @retval returns kStkErrOk on success + @retval returns ksfTkErrOk on success */ - sfeTkError_t writeRegisterWord(uint8_t devReg, uint16_t data); + sfTkError_t writeRegisterWord(uint8_t devReg, uint16_t data); /** @brief Writes a number of bytes starting at the given register's address. - @note sfeTkIBus interface method + @note sfTkIBus interface method @note This method is virtual to allow it to be overridden to support a device that requires a unique impl @param devReg The device's register's address. @param data Data to write. @param length - length of data - @retval kStkErrOk on success + @retval ksfTkErrOk on success */ - sfeTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length); + sfTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length); /** @brief Writes a number of bytes starting at the given register's 16-bit address. @@ -184,10 +170,10 @@ class sfeTkArdI2C : public sfeTkII2C @param data Data to write. @param length - length of data - @retval sfeTkError_t kSTkErrOk on successful execution + @retval sfTkError_t ksfTkErrOk on successful execution */ - sfeTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length); + sfTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length); /** @brief Writes a number of bytes starting at the given register's 16-bit address. @@ -196,39 +182,39 @@ class sfeTkArdI2C : public sfeTkII2C @param data Data to write. @param length - length of data - @retval sfeTkError_t kSTkErrOk on successful execution + @retval sfTkError_t ksfTkErrOk on successful execution */ - sfeTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length); + sfTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length); /** @brief Reads a byte of data from the given register. - @note sfeTkIBus interface method + @note sfTkIBus interface method @param devReg The device's register's address. @param[out] data Data to read. - @retval kStkErrOk on success + @retval ksfTkErrOk on success */ - sfeTkError_t readRegisterByte(uint8_t devReg, uint8_t &data); + sfTkError_t readRegisterByte(uint8_t devReg, uint8_t &data); /** @brief Reads a word of data from the given register. - @note sfeTkIBus interface method + @note sfTkIBus interface method @param devReg The device's register's address. @param[out] data Data to read. - @retval kSTkErrOk on success + @retval ksfTkErrOk on success */ - sfeTkError_t readRegisterWord(uint8_t devReg, uint16_t &data); + sfTkError_t readRegisterWord(uint8_t devReg, uint16_t &data); /** @brief Reads a block of data from the given register. - @note sfeTkIBus interface method + @note sfTkIBus interface method @note This method is virtual to allow it to be overridden to support a device that requires a unique impl @param devReg The device's register's address. @@ -237,9 +223,9 @@ class sfeTkArdI2C : public sfeTkII2C @param[out] readBytes - Number of bytes read - @retval kSTkErrOk on success + @retval ksfTkErrOk on success */ - sfeTkError_t readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes); + sfTkError_t readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes); /** @brief Reads a block of data from the given 16-bit register address. @@ -249,10 +235,10 @@ class sfeTkArdI2C : public sfeTkII2C @param numBytes - Number of bytes to read/length of data buffer @param[out] readBytes - number of bytes read - @retval int returns kSTkErrOk on success, or kSTkErrFail code + @retval int returns ksfTkErrOk on success, or ksfTkErrFail code */ - sfeTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); + sfTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); /** @brief Reads a block of data from the given 16-bit register address. @@ -262,10 +248,10 @@ class sfeTkArdI2C : public sfeTkII2C @param numBytes - Number of bytes to read/length of data buffer @param[out] readBytes - number of bytes read - @retval int returns kSTkErrOk on success, or kSTkErrFail code + @retval int returns ksfTkErrOk on success, or ksfTkErrFail code */ - sfeTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes); + sfTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes); // Buffer size chunk getter/setter /** @@ -303,9 +289,9 @@ class sfeTkArdI2C : public sfeTkII2C TwoWire *_i2cPort; private: - sfeTkError_t writeRegisterRegionAddress(uint8_t *devReg, size_t regLength, const uint8_t *data, size_t length); + sfTkError_t writeRegisterRegionAddress(uint8_t *devReg, size_t regLength, const uint8_t *data, size_t length); - sfeTkError_t readRegisterRegionAnyAddress(uint8_t *devReg, size_t regLength, uint8_t *data, size_t numBytes, + sfTkError_t readRegisterRegionAnyAddress(uint8_t *devReg, size_t regLength, uint8_t *data, size_t numBytes, size_t &readBytes); /** Default buffer chunk size*/ diff --git a/src/sfeTkArdSPI.cpp b/src/sfTkArdSPI.cpp similarity index 65% rename from src/sfeTkArdSPI.cpp rename to src/sfTkArdSPI.cpp index 54741be..a630d8c 100644 --- a/src/sfeTkArdSPI.cpp +++ b/src/sfTkArdSPI.cpp @@ -1,29 +1,17 @@ - -// sfeTkArdSPI.cpp - Arduino SPI implementation for the toolkit - -/* -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#include "sfeTkArdSPI.h" +/** + * @file sfTkArdSPI.h + * @brief Implementation file for the SparkFun Toolkit Arduino SPI driver. + * + * This file contains the Arduino SPI driver for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + +#include "sfTkArdSPI.h" #include // Note: A leading "1" must be added to transfer with register to indicate a "read" @@ -38,7 +26,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. // // Arduino version of init. Will take in a defined SPI port/settings // -sfeTkError_t sfeTkArdSPI::init(SPIClass &spiPort, SPISettings &busSPISettings, uint8_t csPin, bool bInit) +sfTkError_t sfTkArdSPI::init(SPIClass &spiPort, SPISettings &busSPISettings, uint8_t csPin, bool bInit) { // if we don't have a SPI port already if (!_spiPort) @@ -54,7 +42,7 @@ sfeTkError_t sfeTkArdSPI::init(SPIClass &spiPort, SPISettings &busSPISettings, u // SPI settings are needed for every transaction _sfeSPISettings = busSPISettings; - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -62,7 +50,7 @@ sfeTkError_t sfeTkArdSPI::init(SPIClass &spiPort, SPISettings &busSPISettings, u // // Arduino version of init. // -sfeTkError_t sfeTkArdSPI::init(uint8_t csPin, bool bInit) +sfTkError_t sfTkArdSPI::init(uint8_t csPin, bool bInit) { // If the transaction settings are not provided by the user they are built here. SPISettings spiSettings = SPISettings(3000000, MSBFIRST, SPI_MODE3); @@ -76,7 +64,7 @@ sfeTkError_t sfeTkArdSPI::init(uint8_t csPin, bool bInit) // // Arduino version of init. // -sfeTkError_t sfeTkArdSPI::init(bool bInit) +sfTkError_t sfTkArdSPI::init(bool bInit) { return init(cs(), bInit); } @@ -86,13 +74,13 @@ sfeTkError_t sfeTkArdSPI::init(bool bInit) // // Writes a single byte to the device. // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeByte(uint8_t dataToWrite) +sfTkError_t sfTkArdSPI::writeByte(uint8_t dataToWrite) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings _spiPort->beginTransaction(_sfeSPISettings); @@ -105,7 +93,7 @@ sfeTkError_t sfeTkArdSPI::writeByte(uint8_t dataToWrite) digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -113,9 +101,9 @@ sfeTkError_t sfeTkArdSPI::writeByte(uint8_t dataToWrite) // // Writes a word to the device without indexing to a register. // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeWord(uint16_t dataToWrite) +sfTkError_t sfTkArdSPI::writeWord(uint16_t dataToWrite) { return writeRegion((uint8_t *)&dataToWrite, sizeof(uint8_t)) > 0; } @@ -125,13 +113,13 @@ sfeTkError_t sfeTkArdSPI::writeWord(uint16_t dataToWrite) // // Writes an array of data to the device without indexing to a register. // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeRegion(const uint8_t *dataToWrite, size_t length) +sfTkError_t sfTkArdSPI::writeRegion(const uint8_t *dataToWrite, size_t length) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; _spiPort->beginTransaction(_sfeSPISettings); // Signal communication start @@ -144,7 +132,7 @@ sfeTkError_t sfeTkArdSPI::writeRegion(const uint8_t *dataToWrite, size_t length) digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -152,13 +140,13 @@ sfeTkError_t sfeTkArdSPI::writeRegion(const uint8_t *dataToWrite, size_t length) // // Writes a byte to a given register. // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) +sfTkError_t sfTkArdSPI::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings _spiPort->beginTransaction(_sfeSPISettings); @@ -172,7 +160,7 @@ sfeTkError_t sfeTkArdSPI::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -180,9 +168,9 @@ sfeTkError_t sfeTkArdSPI::writeRegisterByte(uint8_t devReg, uint8_t dataToWrite) // // Writes a world to a given register. // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite) +sfTkError_t sfTkArdSPI::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite) { return writeRegisterRegion(devReg, (uint8_t *)&dataToWrite, sizeof(uint8_t)) > 0; } @@ -191,12 +179,12 @@ sfeTkError_t sfeTkArdSPI::writeRegisterWord(uint8_t devReg, uint16_t dataToWrite // // Writes an array of bytes to a given register on the target address // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) +sfTkError_t sfTkArdSPI::writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings before work _spiPort->beginTransaction(_sfeSPISettings); @@ -213,14 +201,14 @@ sfeTkError_t sfeTkArdSPI::writeRegisterRegion(uint8_t devReg, const uint8_t *dat digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } // 16 bit address version ... -sfeTkError_t sfeTkArdSPI::writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) +sfTkError_t sfTkArdSPI::writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings before work _spiPort->beginTransaction(_sfeSPISettings); @@ -236,15 +224,15 @@ sfeTkError_t sfeTkArdSPI::writeRegister16Region(uint16_t devReg, const uint8_t * digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- // 16 bit address and data version ... -sfeTkError_t sfeTkArdSPI::writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) +sfTkError_t sfTkArdSPI::writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings before work _spiPort->beginTransaction(_sfeSPISettings); @@ -260,35 +248,36 @@ sfeTkError_t sfeTkArdSPI::writeRegister16Region16(uint16_t devReg, const uint16_ digitalWrite(cs(), HIGH); _spiPort->endTransaction(); - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- -sfeTkError_t sfeTkArdSPI::readRegisterByte(uint8_t devReg, uint8_t &data) +sfTkError_t sfTkArdSPI::readRegisterByte(uint8_t devReg, uint8_t &data) { size_t nRead; - sfeTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&data, sizeof(uint8_t), nRead); + sfTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&data, sizeof(uint8_t), nRead); - return (retval == kSTkErrOk && nRead == sizeof(uint8_t) ? kSTkErrOk : retval); + return (retval == ksfTkErrOk && nRead == sizeof(uint8_t) ? ksfTkErrOk : retval); } -sfeTkError_t sfeTkArdSPI::readRegisterWord(uint8_t devReg, uint16_t &data) +//--------------------------------------------------------------------------------- +sfTkError_t sfTkArdSPI::readRegisterWord(uint8_t devReg, uint16_t &data) { size_t nRead; - sfeTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&data, sizeof(uint16_t), nRead); + sfTkError_t retval = readRegisterRegion(devReg, (uint8_t *)&data, sizeof(uint16_t), nRead); - return (retval == kSTkErrOk && nRead == sizeof(uint16_t) ? kSTkErrOk : retval); + return (retval == ksfTkErrOk && nRead == sizeof(uint16_t) ? ksfTkErrOk : retval); } //--------------------------------------------------------------------------------- // readRegisterRegion() // // Reads an array of bytes to a given register on the target address // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) +sfTkError_t sfTkArdSPI::readRegisterRegion(uint8_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings _spiPort->beginTransaction(_sfeSPISettings); @@ -308,7 +297,7 @@ sfeTkError_t sfeTkArdSPI::readRegisterRegion(uint8_t devReg, uint8_t *data, size readBytes = numBytes; - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -316,12 +305,12 @@ sfeTkError_t sfeTkArdSPI::readRegisterRegion(uint8_t devReg, uint8_t *data, size // // Reads an array of bytes to a given a 16 bit register on the target address // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::readRegister16Region(uint16_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) +sfTkError_t sfTkArdSPI::readRegister16Region(uint16_t devReg, uint8_t *data, size_t numBytes, size_t &readBytes) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings _spiPort->beginTransaction(_sfeSPISettings); @@ -341,7 +330,7 @@ sfeTkError_t sfeTkArdSPI::readRegister16Region(uint16_t devReg, uint8_t *data, s readBytes = numBytes; - return kSTkErrOk; + return ksfTkErrOk; } //--------------------------------------------------------------------------------- @@ -349,12 +338,12 @@ sfeTkError_t sfeTkArdSPI::readRegister16Region(uint16_t devReg, uint8_t *data, s // // Reads an array of uint16 to a given a 16 bit register on the target address // -// Returns kSTkErrOk on success +// Returns ksfTkErrOk on success // -sfeTkError_t sfeTkArdSPI::readRegister16Region16(uint16_t devReg, uint16_t *data, size_t numBytes, size_t &readWords) +sfTkError_t sfTkArdSPI::readRegister16Region16(uint16_t devReg, uint16_t *data, size_t numBytes, size_t &readWords) { if (!_spiPort) - return kSTkErrBusNotInit; + return ksfTkErrBusNotInit; // Apply settings _spiPort->beginTransaction(_sfeSPISettings); @@ -374,5 +363,5 @@ sfeTkError_t sfeTkArdSPI::readRegister16Region16(uint16_t devReg, uint16_t *data readWords = numBytes; - return kSTkErrOk; + return ksfTkErrOk; } \ No newline at end of file diff --git a/src/sfeTkArdSPI.h b/src/sfTkArdSPI.h similarity index 59% rename from src/sfeTkArdSPI.h rename to src/sfTkArdSPI.h index 8ab0ce4..95f44d3 100644 --- a/src/sfeTkArdSPI.h +++ b/src/sfTkArdSPI.h @@ -1,46 +1,32 @@ - - -// sfeTkBusSPI.h - Defines the Arduino SPI interface for the SparkFun Toolkit SDK - -/* - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ +/** + * @file sfTkArdSPI.cpp + * @brief header file for the SparkFun Toolkit Arduino SPI driver. + * + * This file contains the Arduino SPI header for the SparkFun Toolkit library. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ #pragma once -#include "sfeTkArduino.h" +#include "sfTkArduino.h" #include -#include +#include /** @brief This class implements the IBus interface for an SPI Implementation on Arduino */ -class sfeTkArdSPI : public sfeTkISPI +class sfTkArdSPI : public sfTkISPI { public: /** @brief Constructor for Arduino SPI bus object of the toolkit */ - sfeTkArdSPI(void) : _spiPort(nullptr) + sfTkArdSPI(void) : _spiPort(nullptr) { } @@ -49,7 +35,7 @@ class sfeTkArdSPI : public sfeTkISPI @param csPin The CS Pin for the device */ - sfeTkArdSPI(uint8_t csPin) : sfeTkISPI(csPin) + sfTkArdSPI(uint8_t csPin) : sfTkISPI(csPin) { } /** @@ -57,7 +43,7 @@ class sfeTkArdSPI : public sfeTkISPI @param rhs source of the copy operation */ - sfeTkArdSPI(sfeTkArdSPI const &rhs) : sfeTkISPI(), _spiPort{rhs._spiPort}, _sfeSPISettings{rhs._sfeSPISettings} + sfTkArdSPI(sfTkArdSPI const &rhs) : sfTkISPI(), _spiPort{rhs._spiPort}, _sfeSPISettings{rhs._sfeSPISettings} { } @@ -65,9 +51,9 @@ class sfeTkArdSPI : public sfeTkISPI @brief Assignment copy operator for Arduino SPI bus object of the toolkit @param rhs The right hand side of the assignment. - @return sfeTkArdSPI& - The left hand side of the assignment. + @return sfTkArdSPI& - The left hand side of the assignment. */ - sfeTkArdSPI &operator=(const sfeTkArdSPI &rhs) + sfTkArdSPI &operator=(const sfTkArdSPI &rhs) { _spiPort = rhs._spiPort; _sfeSPISettings = rhs._sfeSPISettings; @@ -80,9 +66,9 @@ class sfeTkArdSPI : public sfeTkISPI @param bInit Init the device - default is false. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t init(bool bInit = false); + sfTkError_t init(bool bInit = false); /** @brief Method sets up the required SPI settings. @@ -91,9 +77,9 @@ class sfeTkArdSPI : public sfeTkISPI @param csPin The CS Pin for the device @param bInit Init the device - default is false. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t init(uint8_t csPin, bool bInit = false); + sfTkError_t init(uint8_t csPin, bool bInit = false); /** @brief Method sets up the required SPI settings. @@ -103,27 +89,27 @@ class sfeTkArdSPI : public sfeTkISPI @param csPin The CS Pin for the device @param bInit This flag tracks whether the bus has been initialized. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t init(SPIClass &spiPort, SPISettings &busSPISettings, uint8_t csPin, bool bInit = false); + sfTkError_t init(SPIClass &spiPort, SPISettings &busSPISettings, uint8_t csPin, bool bInit = false); /** @brief Write a single byte to the device @param data Data to write. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeByte(uint8_t data); + sfTkError_t writeByte(uint8_t data); /** @brief Write a word to the device without indexing to a register. @param data Data to write. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeWord(uint16_t data); + sfTkError_t writeWord(uint16_t data); /** @brief Write an array of data to the device without indexing to a register. @@ -131,9 +117,9 @@ class sfeTkArdSPI : public sfeTkISPI @param data Data to write @param length Length of Data - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegion(const uint8_t *data, size_t length); + sfTkError_t writeRegion(const uint8_t *data, size_t length); /** @brief Write a single byte to the given register @@ -141,9 +127,9 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param data Data to write. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegisterByte(uint8_t devReg, uint8_t data); + sfTkError_t writeRegisterByte(uint8_t devReg, uint8_t data); /** @brief Write a single word to the given register @@ -151,9 +137,9 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param data Data to write. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegisterWord(uint8_t devReg, uint16_t data); + sfTkError_t writeRegisterWord(uint8_t devReg, uint16_t data); /** @brief Writes a number of bytes starting at the given register's address. @@ -163,9 +149,9 @@ class sfeTkArdSPI : public sfeTkISPI @param data Data to write. @param length - length of data - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length); + sfTkError_t writeRegisterRegion(uint8_t devReg, const uint8_t *data, size_t length); /** @brief Writes a number of bytes starting at the given register's address. @@ -175,9 +161,9 @@ class sfeTkArdSPI : public sfeTkISPI @param data Data to write. @param length - length of data - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length); + sfTkError_t writeRegister16Region(uint16_t devReg, const uint8_t *data, size_t length); /** @brief Writes a number of uint16s starting at the given register's address. @@ -187,9 +173,9 @@ class sfeTkArdSPI : public sfeTkISPI @param data Data to write. @param length - length of data - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length); + sfTkError_t writeRegister16Region16(uint16_t devReg, const uint16_t *data, size_t length); /** @brief Read a single byte from the given register @@ -197,9 +183,9 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param[out] data Data to read. - @retval sfeTkError_t - kSTkErrOk on success + @retval sfTkError_t - ksfTkErrOk on success */ - sfeTkError_t readRegisterByte(uint8_t devReg, uint8_t &data); + sfTkError_t readRegisterByte(uint8_t devReg, uint8_t &data); /** @brief read a single word to the given register @@ -207,9 +193,9 @@ class sfeTkArdSPI : public sfeTkISPI @param devReg The device's register's address. @param[out] data Data to write. - @retval sfeTkError_t - true on success + @retval sfTkError_t - true on success */ - sfeTkError_t readRegisterWord(uint8_t devReg, uint16_t &data); + sfTkError_t readRegisterWord(uint8_t devReg, uint16_t &data); /** @brief Reads a block of data from the given register. @@ -220,9 +206,9 @@ class sfeTkArdSPI : public sfeTkISPI @param numBytes - length of data/size of data buffer @param[out] readBytes - Number of bytes read - @retval sfeTkError_t - true on success + @retval sfTkError_t - true on success */ - virtual sfeTkError_t readRegisterRegion(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); + virtual sfTkError_t readRegisterRegion(uint8_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); /** @brief Reads a block of data from the given register. @@ -233,9 +219,9 @@ class sfeTkArdSPI : public sfeTkISPI @param numBytes - Length of data to read/size of data buffer @param[out] readBytes - Number of bytes read - @retval sfeTkError_t - true on success + @retval sfTkError_t - true on success */ - virtual sfeTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); + virtual sfTkError_t readRegister16Region(uint16_t reg, uint8_t *data, size_t numBytes, size_t &readBytes); /** @brief Reads a block of data from the given register. @@ -246,9 +232,9 @@ class sfeTkArdSPI : public sfeTkISPI @param numBytes - Length of data to read/size of data buffer @param[out] readBytes - Number of bytes read - @retval sfeTkError_t - true on success + @retval sfTkError_t - true on success */ - virtual sfeTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes); + virtual sfTkError_t readRegister16Region16(uint16_t reg, uint16_t *data, size_t numBytes, size_t &readBytes); protected: // note: The instance data is protected, allowing access if a sub-class is diff --git a/src/sfTkArduino.cpp b/src/sfTkArduino.cpp new file mode 100644 index 0000000..49b5aef --- /dev/null +++ b/src/sfTkArduino.cpp @@ -0,0 +1,26 @@ +/** + * @file sfTkArduino.cpp + * @brief Implementation file for the SparkFun Toolkit Arduino layer + * + * This file contains the implementation for the SparkFun Toolkit library Arduino layer. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + +#include + +// Implements the sfToolkit functions for the Arduino platform + +void sftk_delay_ms(uint32_t ms) +{ + delay(ms); +} + +uint32_t sftk_ticks_ms(void) +{ + return millis(); +} \ No newline at end of file diff --git a/src/sfTkArduino.h b/src/sfTkArduino.h new file mode 100644 index 0000000..f79ddcd --- /dev/null +++ b/src/sfTkArduino.h @@ -0,0 +1,28 @@ + +/** + * @file sfTkArduino.h + * @brief header file for the SparkFun Toolkit Arduino layer + * + * This file contains the header for the SparkFun Toolkit library Arduino layer. + * + * @author SparkFun Electronics + * @date 2024-2025 + * @copyright Copyright (c) 2024-2025, SparkFun Electronics Inc. This project is released under the MIT License. + * + * SPDX-License-Identifier: MIT + */ + +#pragma once + +// Purpose: +// +// "Arduino-ized" value of toolkit values constants" + +// Just include the toolkit headers + +#include + +// Arduino-ize our byte order types + +const sfTkByteOrder SFTK_MSBFIRST = sfTkByteOrder::BigEndian; +const sfTkByteOrder SFTK_LSBFIRST = sfTkByteOrder::LittleEndian; \ No newline at end of file diff --git a/src/sfeTk/sfeTkError.h b/src/sfeTk/sfeTkError.h deleted file mode 100644 index 3f00841..0000000 --- a/src/sfeTk/sfeTkError.h +++ /dev/null @@ -1,64 +0,0 @@ - -// sfeTkError.h -// -// General header file for the SparkFun Toolkit -/* -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#pragma once - -#include - -/** - * General Concept - * A SparkFun Toolkit error system. The goal is to keep this simple. - * - * This mimics a variety of systems, using an int type for error codes, - * where: - * 0 = okay - * -1 = general failure - * >0 = an informative error - * - * Since *subsystems* in the toolkit can have their own errors, - * A start range for these errors are defined. Values > than this value - * define the errors for the set subsystem. These start ranges are set - * in this file, with actual error values defined in the the respective - * subsystem header files. - * - */ -typedef int32_t sfeTkError_t; - -// General errors - -/** - * @brief General error code for a failure. Note all errors are negative. - */ -const sfeTkError_t kSTkErrFail = -1; // general fail -/** - * @brief The error code value for success. This is always 0. - */ -const sfeTkError_t kSTkErrOk = 0; // success - -/** - * @brief A base value for bus errors. All bus errors are greater than this value, in the 1000 range - */ -const sfeTkError_t kSTkErrBaseBus = 0x1000; diff --git a/src/sfeTk/sfeTkISPI.h b/src/sfeTk/sfeTkISPI.h deleted file mode 100644 index b77ea9c..0000000 --- a/src/sfeTk/sfeTkISPI.h +++ /dev/null @@ -1,97 +0,0 @@ - -// sfeTkISPI.h -// -// Defines the SPI communication bus interface for the SparkFun Electronics Toolkit -/* - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#pragma once - -#include "sfeTkIBus.h" - -/** - * @brief Interface that defines the SPI communication bus for the SparkFun Electronics Toolkit. - * - * The SPI bus interface extends the IBus interface and adds the ability to set and get the CS pin. - */ - -const uint8_t kBusTypeSPI = 0x02; -class sfeTkISPI : public sfeTkIBus -{ - public: - /**-------------------------------------------------------------------------- - @brief Constructor for the SPI bus - - */ - sfeTkISPI() : _cs{kNoCSPin} - { - } - - /**-------------------------------------------------------------------------- - @brief Constructor for the SPI bus - - @param csPin The CS Pin for the device - - */ - sfeTkISPI(uint8_t csPin) : _cs{csPin} - { - } - - /**-------------------------------------------------------------------------- - @brief setter for the CS Pin - - @param devCS The device's CS Pin - - */ - virtual void setCS(uint8_t devCS) - { - _cs = devCS; - } - - /**-------------------------------------------------------------------------- - @brief getter for the cs pin - - @retval uint8_t returns the CS pin for the device - - */ - virtual uint8_t cs(void) - { - return _cs; - } - - /**-------------------------------------------------------------------------- - @brief A constant for no CS pin - */ - static constexpr uint8_t kNoCSPin = 0; - - virtual uint8_t type(void) - { - return kBusTypeSPI; - } - - private: - /** The internal storage of the _cs value*/ - uint8_t _cs; -}; - -//}; diff --git a/src/sfeTk/sfeToolkit.h b/src/sfeTk/sfeToolkit.h deleted file mode 100644 index e634a24..0000000 --- a/src/sfeTk/sfeToolkit.h +++ /dev/null @@ -1,61 +0,0 @@ - -// sfeToolkit.h -// -// General header file for the SparkFun Toolkit -/* - -The MIT License (MIT) - -Copyright (c) 2024 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -*/ - -#pragma once - -#include - -/** - @brief Common include file for the core of the SparkFun Electronics Toolkit -*/ -#include "sfeTkError.h" - - -// byte order types/enum -enum class sfeTKByteOrder : uint8_t -{ - BigEndian = 0x01, - LittleEndian = 0x02 -}; - -// Note - toolkit *functions* start with sftk_ to avoid name collisions - -// Function to determine the byte order of the system -sfeTKByteOrder sftk_system_byteorder(void); - -uint8_t sftk_byte_swap(uint8_t i); -uint16_t sftk_byte_swap(uint16_t i); -uint32_t sftk_byte_swap(uint32_t i); - - -// Area for platform specific implementations. The interface/functions are -// defined here, with the expectation that the platform provides the implementation. - -// delay in milliseconds -void sftk_delay_ms(uint32_t ms); - -// ticks in milliseconds -uint32_t sftk_ticks_ms(void); \ No newline at end of file diff --git a/src/sfeTkArduino.cpp b/src/sfeTkArduino.cpp deleted file mode 100644 index fd5cca2..0000000 --- a/src/sfeTkArduino.cpp +++ /dev/null @@ -1,37 +0,0 @@ -/* -@brief sfeTkArduino.cpp - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#include - -// Implements the sfeToolkit functions for the Arduino platform - -void sftk_delay_ms(uint32_t ms) -{ - delay(ms); -} - -uint32_t sftk_ticks_ms(void) -{ - return millis(); -} \ No newline at end of file diff --git a/src/sfeTkArduino.h b/src/sfeTkArduino.h deleted file mode 100644 index 5ebb017..0000000 --- a/src/sfeTkArduino.h +++ /dev/null @@ -1,39 +0,0 @@ - -/* -@brief sfeTkArduino.h - -The MIT License (MIT) - -Copyright (c) 2023 SparkFun Electronics - -Permission is hereby granted, free of charge, to any person obtaining a -copy of this software and associated documentation files (the "Software"), -to deal in the Software without restriction, including without limitation -the rights to use, copy, modify, merge, publish, distribute, sublicense, -and/or sell copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following conditions: The -above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED -"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT -NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR -PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN -ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. - -*/ - -#pragma once - -// Purpose: -// -// "Arduino-ized" value of toolkit values constants" - -// Just include the toolkit headers - -#include - -// Arduino-ize our byte order types - -const sfeTKByteOrder SFTK_MSBFIRST = sfeTKByteOrder::BigEndian; -const sfeTKByteOrder SFTK_LSBFIRST = sfeTKByteOrder::LittleEndian; \ No newline at end of file