From 19f396322cee49c723f2fe38571d2199ce209567 Mon Sep 17 00:00:00 2001 From: dave Date: Sun, 22 Sep 2024 20:25:00 +0100 Subject: [PATCH] #9 a few small fixes to pages --- content/arduino-libraries/io-abstraction.md | 3 +- .../arduino-logging-with-io-logging.md | 20 ++++- .../i2c-wire-calls-over-arduino-mbed.md | 47 ++++++++-- ...bstraction-troubleshooting-unit-testing.md | 2 +- .../simple-test-unit-test-arduino-mbed.md | 90 ------------------- .../rendering-with-themes-icons-grids.md | 14 +-- .../layouts/partials/widgets/sidebar.html | 2 +- 7 files changed, 70 insertions(+), 108 deletions(-) delete mode 100644 content/arduino-libraries/io-abstraction/simple-test-unit-test-arduino-mbed.md diff --git a/content/arduino-libraries/io-abstraction.md b/content/arduino-libraries/io-abstraction.md index bbb91ed..b1f6360 100644 --- a/content/arduino-libraries/io-abstraction.md +++ b/content/arduino-libraries/io-abstraction.md @@ -62,9 +62,8 @@ Need help with a commercial design, or want a customised version for your hardwa * [Seamless EEPROM implementations, AVR, Arduino, I2C]({{< relref "eeprom-impl-seamless-8-and-32-bit.md">}}) -## Logging, text utilities and unit testing +## Logging, text utilities and unit testing helper classes * [Arduino logging with IoAbstraction]({{< relref "arduino-logging-with-io-logging.md">}}) * [Text Utilities and helpers]({{< relref "text-utilities-and-helpers.md" >}}) * [Troubleshooting, IoAbstraction mock implementations]({{< relref "ioabstraction-troubleshooting-unit-testing.md">}}) -* [Simple Test - simple no frills unit test framework for Arduino and mbed]({{< relref "simple-test-unit-test-arduino-mbed.md">}}) diff --git a/content/arduino-libraries/io-abstraction/arduino-logging-with-io-logging.md b/content/arduino-libraries/io-abstraction/arduino-logging-with-io-logging.md index dee7f03..5d59582 100644 --- a/content/arduino-libraries/io-abstraction/arduino-logging-with-io-logging.md +++ b/content/arduino-libraries/io-abstraction/arduino-logging-with-io-logging.md @@ -14,9 +14,9 @@ toc_needed = true weight = 5 +++ -Logging is part of the IoAbstraction offering, it has a moderately complete logging framework that is still lightweight enough to work on small boards. It can easily be turned off completely for very small boards too. Both IoAbstraction and tcMenu use this logging to provide information about internal state and operations. +Logging is part of the TcMenu offering provided by library `TcMenuLog`, it has a moderately complete logging framework that is still lightweight enough to work on small boards. It can easily be turned off completely for very small boards too. TaskManagerIO, IoAbstraction and tcMenu use this logging to provide information about internal state and operations. -The logging is fully integrated into both IoAbstraction and TcMenu, and this change is backward compatible at a code level. +You can also use this logging framework in your own project code, regardless if you're using any other of our libraries. {{< blockClear "left" >}} @@ -26,11 +26,15 @@ To use the logging in your project you first include the logging header file: #include -Secondly you define the following build switch to turn on logging: `IO_LOGGING_DEBUG`. For example on platformIO that would be: +Should an older version of Arduino need the library header match the library name, you can also include: + + #include + +Next, you define the following build switch to turn on logging: `IO_LOGGING_DEBUG`. For example on platformIO that would be: build_flags = -DIO_LOGGING_DEBUG=1 -If you are using the original Arduino IDE, it does not support build flags, you can in this case open IoLogging.h in the IoAbstraction library and uncomment the entry to define it in there. This would need to be done after each upgrade and is not recommended. +If you are using the original Arduino IDE, it does not support build flags, you can in this case open `IoLogging.h` in the TcMenuLog library and uncomment the entry to define it in there. This would need to be done after each upgrade and is not recommended. You can set the logging levels at compile time using `IO_LOGGING_DEFAULT_LEVEL` by ORing together entries from `SerLoggingLevel`. An is shown below for only warning and error logs: @@ -107,6 +111,14 @@ On mbed proper (IE using mbed without Arduino), **we must define the print inter BufferedSerial serPort(USBTX, USBRX); MBedLogger LoggingPort(serPort); +Instead of the above, you can use the following macro that always work, on any platform. + + IOLOG_MBED_PORT_IF_NEEDED(txPin, rxPin) + +You should always start the serial port. For example on Arduino you may need to start the serial port youre using with something like `Serial.begin(115200);`, and there is also a macro for that: + + IOLOG_START_SERIAL + In summary, the logging framework is a compromise between functionality and size, biased slightly toward size. ## Example of the logging format on device diff --git a/content/arduino-libraries/io-abstraction/i2c-wire-calls-over-arduino-mbed.md b/content/arduino-libraries/io-abstraction/i2c-wire-calls-over-arduino-mbed.md index 805191b..47f56a9 100644 --- a/content/arduino-libraries/io-abstraction/i2c-wire-calls-over-arduino-mbed.md +++ b/content/arduino-libraries/io-abstraction/i2c-wire-calls-over-arduino-mbed.md @@ -1,5 +1,5 @@ +++ -title = "IOA I2C/Wire abstraction that works Across Arduino and mbed" +title = "SPI and I2C/Wire abstraction that works on Arduino, mbed, PicoSDK" description = "" tags = [ "arduino", "digital-io", "library" ] type = "blog" @@ -13,9 +13,13 @@ titleimg = "/products/arduino-libraries/images/electronics/arduino/power/io-abst weight = 2 +++ -IoAbstraction 2.0 onwards has core I2C/Wire functionality provided by several functions, these abstract the use of I2C over Arduino and mbed, and over time the implementation of these will be improved, such that asynchronous behaviour will be possible on certain boards. +IoAbstraction has core I2C/Wire and SPI functionality provided by several functions, these abstract the use of I2C and SPI over Arduino, mbed, PicoSDK and other supported platforms. Over time the implementation of these will be improved, such that asynchronous behaviour will be possible on certain boards. -Prior to 2.0, we had conditional I2C code scattered around the project, but now nearly all such functionality is separated out by platform, and sometimes even by board, we've made this available through the API, so you can use it too. +Prior to 2.0, we had conditional I2C code scattered around the project, but now nearly all such functionality is separated out by platform, and sometimes even by board simplifying access. + +{{< blockClear "left" >}} + +## Wire/I2C abstraction We wrap up the wire object with `WireType`; which on Arduino it is a TwoWire pointer and on mbed it is an I2C pointer. For example the default wire type on Arduino would be `&Wire`. Be aware that this is not a complete replacement for Wire/I2C, it is a simple set of calls for reading and write from I2C where the device is master. It works on a very wide range of boards without needing code changes. @@ -41,7 +45,7 @@ On all boards there is a lock around the i2c bus, this ensures that only one thr extern SimpleSpinLock i2cLock; -## Reading bytes from the bus +### Reading bytes from the bus To read bytes from the bus: @@ -55,7 +59,7 @@ Where: * len is the number of bytes to read * returns true if the read is fully successful, otherwise false. -## Writing bytes to the bus +### Writing bytes to the bus bool ioaWireWriteWithRetry(WireType pI2c, int address, const uint8_t* buffer, size_t len, int retriesAllowed = 0, bool sendStop = true); @@ -69,6 +73,39 @@ Where: * retriesAllowed is the number of times to attempt the operation, 0 = only once. * sendStop allows you to keep the bus open ready for a repeated start, use with care. +## The SPI abstraction + +You can use SPI regardless of platform using the SPI abstraction. This is used in a few places within IoAbstraction so is already quite stable. + +### Construction of SPI abstraction + +In order to create an instance, you first need to create an `SPIWithSettings` object: + + SPIWithSettings spiObj(&SPIBus, csPin); + +Then in your code somewhere: + + spiObj.init(); + +Where: + +* SPIBus is the SPI bus on your hardware, for example on Arduino this may be `&SPI` for example. +* csPin is the chip select pin, doing any transfers automatically selects the pin first. + +The class is quite small and has copy constructors, so you can safely copy it over by value, and this is often how its used within IoAbstraction. + +### Transferring data over SPI + +Normally on SPI you read and write data at the same time, therefore to `transfer` data call the following method that will first select the chip, do the transfer, and then deselect the chip: + + uint8_t readWriteData[dataSize]; + bool ok = spiObj.transferSPI(readWriteData, dataSize); + +Where + +* readWriteData is a uint8_t array of at least dataSize, the read data is put into the array after calling. +* dataSize is the number of bytes to transfer + {{< refdocs title="You can read more about this in the reference documentation" src="/ioabstraction/html/index.html" >}} [Go back to the IoAbstraction page]({{< relref "io-abstraction.md" >}}) \ No newline at end of file diff --git a/content/arduino-libraries/io-abstraction/ioabstraction-troubleshooting-unit-testing.md b/content/arduino-libraries/io-abstraction/ioabstraction-troubleshooting-unit-testing.md index f324398..b2d7478 100644 --- a/content/arduino-libraries/io-abstraction/ioabstraction-troubleshooting-unit-testing.md +++ b/content/arduino-libraries/io-abstraction/ioabstraction-troubleshooting-unit-testing.md @@ -24,7 +24,7 @@ Within the MockIoAbstraction.h header there is an implementation of BasicIoAbstr ## Mock objects for use with Unit testing -This library itself is quite well tested using our simple test facilities, and further it makes unit testing your code easier. There is a MockIoAbstraction that provides very easy support for mocking out an IoAbstraction. You just provide how many `sync()` calls to store in the internal buffer: +This library itself is quite well tested, and further it makes unit testing your code easier. There is a MockIoAbstraction that provides very easy support for mocking out an IoAbstraction. You just provide how many `sync()` calls to store in the internal buffer: MockedIoAbstraction mockIo(numberOfCycles = 6); diff --git a/content/arduino-libraries/io-abstraction/simple-test-unit-test-arduino-mbed.md b/content/arduino-libraries/io-abstraction/simple-test-unit-test-arduino-mbed.md deleted file mode 100644 index 14a1120..0000000 --- a/content/arduino-libraries/io-abstraction/simple-test-unit-test-arduino-mbed.md +++ /dev/null @@ -1,90 +0,0 @@ -+++ -title = "Simple Test - unit test framework for Arduino and mbed" -description = "" -tags = [ "arduino", "library" ] -type = "blog" -date = "2022-11-16" -author = "dave" -menu = "io-abstraction" -githublink = "https://github.com/TcMenu/IoAbstraction" -referenceDocs = "/ioabstraction/html/index.html" -banner = "/images/electronics/arduino/tcMenu/ioa-logging-example.jpg" -weight = 5 -+++ - -Simple test is a no-frills unit testing framework that works on Arduino and mbed. It sits on top of IoAbstraction and SimpleCollections and works on a very wide range of Arduino boards and mbed. It uses a similar method of test creation to AUnit, and you'll probably find much of this very familiar. - -Why did we write this? We really liked using AUnit library, and had four sets of embedded tests that were based on that library. Unfortunately, as time went by more and more of the boards the libraries needed to support dropped off the supported list. This is not as complete as AUnit, it is the least number of components that provide a unit test framework. It meets our needs, it _might_ just meet yours too. - -In order to see output from the unit tests, you'll need to turn on [the internal IoLogging logger]({{< relref "arduino-logging-with-io-logging.md">}}) - -## Getting started writing a unit test - -First create a directory, and put a main sketch file in it. We recommend your main file be a `cpp` file and not an `ino`. The contents should look like - - #include - #include - - using namespace SimpleTest; - - // This makes the test mbed compatible, it will create a UsbSerial object in mbed - // and assign it to TX and RX. It is ignored on Arduino - IOLOG_MBED_PORT_IF_NEEDED(USBTX, USBRX) - - void setup() { - // starts the serial component and sets the speed to 112500 - IOLOG_START_SERIAL - // this prepares the tests - startTesting(); - } - - // this creates a standard run loop, on mbed it creates a main - DEFAULT_TEST_RUNLOOP - -With this in place we can now write our first test, we start by creating the test with a global `test(name)` block as shown below. This creates and records a test to be run during the run phase later on. Note that expected values are always first with any equality tests. - - test(myImportantTest) { - // numeric equality - assertEquals(10, 5 + 5); - assertLessThan(10, 9); - assertMoreThan(10, 11); - assertEquals('A', 'A'); - - // direct boolean equality - assertFalse(false); - assertTrue(true); - fail("boom"); - - // assert on string equality - assertStringEquals("hello", "hello"); - - // assert that a float is near a given value - assertFloatNear(10.4, 10.4001, 0.01); - } - -You can also write tests that have fixtures, these give the advantage of having state within the fixture class, and also the `setup` and `teardown` methods are called before/after tests. Example below: - - class MyTestFixture : public SimpleTest::UnitTestExecutor { - private: - int myNum = 0; - public: - void setup() override { - myNum = 10; - } - - void teardown() override { - myNum = 0; - } - - bool isMyNum10() { return myNum == 10; } - } - - testF(MyTestFixture, testNumIs10) { - assertTrue(isMyNum10()); - } - -What happened here, we created the fixture class when the testF was encountered, an instance is created and stored, once executed the `setup()` runs first, then the test method itself, finally `teardown()` is called. You can hold any state you like in the class too. - -See the reference documentation for more information. - -[Go back to the IoAbstraction page]({{< relref "io-abstraction.md" >}}) diff --git a/content/arduino-libraries/tc-menu/themes/rendering-with-themes-icons-grids.md b/content/arduino-libraries/tc-menu/themes/rendering-with-themes-icons-grids.md index c16bf1c..76bf7b8 100644 --- a/content/arduino-libraries/tc-menu/themes/rendering-with-themes-icons-grids.md +++ b/content/arduino-libraries/tc-menu/themes/rendering-with-themes-icons-grids.md @@ -69,7 +69,7 @@ Here is an example series of settings from one of our themes, let's discuss what .withNativeFont(itemFont.fontData, itemFont.fontMag) .withSpacing(1); -Firstly the dimensions are configured automatically by calling `dimensionsFromRenderer` this sets the display sizes by querying the display plugin. Then the selected colors are chosen using the RGB macro for each color. Read more about `color_t` and the `RGB` macro below. +Firstly the dimensions are configured automatically by calling `dimensionsFromRenderer` this sets the display sizes by querying the display plugin. Then the selected colors are chosen using the `RGB` macro for each color. As you'd probably expect by convention the `RGB` macro takes red, green and blue parameters between `0` and `255`. After that the item and title padding are configured, you can see we demonstrate both ways to construct a padding object (either all sides same, or separate value for each). The padding is within the rectangle of a menu item, and "pads out" the rectangle's size. You configure the title and item spacing separately (as they are usually different). @@ -123,11 +123,13 @@ You can also change the font, color, padding, size and default justification at * Default settings when no others match * Last chance item that's compiled in just in-case there is a severe mis-configuration to avoid returning `nullptr`. -To change the default settings use `setDrawingPropertiesDefault` on the factory, providing the component type and the drawing settings. This will take effect when there are no other overrides +To change the default settings use `themeBuilder.defaultActionProperties()`, `themeBuilder.defaultItemProperties()` or `themeBuilder.defaultTitleProperties()` on a theme builder. This will take effect when there are no other overrides -To change the properties for all items that belong to a submenu use `setDrawingPropertiesForItem` on the factory, providing the component type and drawing settings. This will take effect when there are no item level overrides. +To change the settings for all items that belong to a submenu use `themeBuilder.submenuPropertiesActionOverride(subMenuItem)`, `themeBuilder.submenuPropertiesActionOverride(subMenuItem)` on theme builder, providing the menu to apply these settings to. This will take effect when there are no item level overrides. -To change the properties for a single item use `setDrawingPropertiesAllInSub` on the factory, providing the component type and drawing settings. This item will always have priority over anything else. +To change the properties for a single item use `themeBuilder.menuItemOverride(menuItem)` on theme builder, providing the menu item. This item will always have priority over anything else. Important note that if you apply changes at the item level, it is normally best to manually set the `row(..)` to keep control of the ordering. + +These all use chained builder syntax as described elsewhere in this guide. You adjust the settings as desired, and finally you must call the `apply()` method. See below for examples. ### Creating two icon menu items on the same row @@ -147,7 +149,7 @@ Here we present an example theme builder layout to show how to override two menu In the above, the row and column upon which the item should appear in configured with `onRowCol(row, col, columnsOnRow)` and then the renderer is told to draw as an icon. Lastly, and very importantly we call `apply()`. -### Overriding a single item's palette or border +### Overriding a single item's palette, border or font Let's say we want an item to have a different palette, border, and justify differently: @@ -155,6 +157,8 @@ Let's say we want an item to have a different palette, border, and justify diffe .withJustification(GridPosition::JUSTIFY_LEFT_NO_VALUE) .withBorder(MenuBorder(1)) .withPalette(specialPalette) + .withAdaFont(myAdafruitFontPtr) + .onRow(1) // on the first row .apply(); ### Advanced - Overriding submenu drawing diff --git a/themes/belter/layouts/partials/widgets/sidebar.html b/themes/belter/layouts/partials/widgets/sidebar.html index 65b2178..d284a9d 100644 --- a/themes/belter/layouts/partials/widgets/sidebar.html +++ b/themes/belter/layouts/partials/widgets/sidebar.html @@ -15,7 +15,7 @@

Share on social sites

{{ end }} {{ if .File }} - + Correct or Improve this page {{ else }}