installation instructions incorrect and cause UNOR4 issue

[paulvha]

Subject of the issue

I have tried to install the Sparkfun RA6M5 library following the instructions on https://docs.sparkfun.com/SparkFun_Thing_Plus_RA6M5/software_overview-arduino/. These instructions are NOT correct.

Your workbench

Ubuntu 22.04
Arduino IDE 1.8.16

Steps to reproduce

It is NOT located at:./arduino/hardware/renesas_portenta// directory of the packages folder.
BUT ./arduino/hardware/renesas_uno// directory of the packages folder.

Creating a folder with a level higher did not work :
For example, if the current version is 1.1.0, users can name the new directory 1.2.0. and then copy the Sparkfun core code in that.
It did not work. After restart of the IDE I only continued to see the original UNOR4's.
I had rename the original 1.1.0 to hidden .1.1.0 and rename the 1.2.0 to 1.1.0. After that restart the IDE.

When now selecting the RA6M5 board it will NOT be at : Tools > Board > Arduino Renesas Portenta Boards > SparkFun Thing Plus RA6M5
but at Tools > Board > Sparkfun Renesas Thing Plus Boards > SparkFun Thing Plus RA6M5

The really bad news is that I need to rename the 1.1.0 folders in the renesas_uno folder every time I switch between UNOR4 and RA6M5.

advice / request

Better instruction would be to use the original Arduino UNOR4 library and add the variant manually.

regards
Paul

[santaimpersonator]

Having looked into the issue, there are a few problems with the initial information you provided:

• I'd recommend using the latest Arduino IDE (v2.x.x).
  • You will run into versioning issues of the Arduino cores within the Arduino IDE 1.x.x (i.e. it has trouble recognizing new installation versions; that are manually added).
  • Also, the Arduino IDE 1.x.x is considered legacy software by Arduino. Therefore, we have followed their lead and are pointing users to the latest version (which some of the core "issues" of the previous version)
• The wrong Arduino core is being installed. You need to install the Arduino core for the Renesas Portenta Boards, which is different from the Arduino core of the UNO R4 boards:
  
• Additionally, part of the reason you are experiencing issues is that you are installing the Arduino core in a local directory: /home/$USER/Arduino/hardware/
  • I would recommend installing the Renesas-Arduino core, from the Board Manager in the Arduino IDE. That should install the hardware files and tools of the Arduino core in the /home/$USER/.arduino15/packages/ directory. (This will be explained further, in the next comments)

[santaimpersonator]

To address the incorrect installation instructions, I followed them on an Ubuntu distro. Our instructions worked fine, with a few caveats:

• The Arduino core versioning number issue, as mentioned above for the legacy version of the Arduino IDE.
  • We recommend using the Arduino IDE v2.x.x to avoid the issue; otherwise, you'll need to name the folder with the same version number.
  • This will allow you the option to have multiple version folders in the directory. The Arduino IDE will recognize the latest version number, when opened.
    • While this doesn't address the renaming issue, it does reduce the need to overwrite files each time.
    • Additionally, it will function with the changes for the FastLED library
• We don't include the original Portenta C33 board in our ported version of the Arduino core. This is an intentional choice we made for the documentation, for several reasons:
  • The instructions for our ported Arduino core, are meant to be temporary.
    • We are currently waiting on a pull request: Add SparkFun Thing Plus RA6M5. arduino/ArduinoCore-renesas#290
    • If the official Arduino core gets updated w/o our pull request, we'd have to update the ported Arduino core. This adds unnecessary maintenance (for the reason below)
  • The Renesas Arduino core relies on linkers for its USB driver installation and board recognition.
    • This can be seen here: https://github.com/arduino/ArduinoCore-renesas/tree/main/cores/arduino/tinyusb
    • These files would need to be "rebuilt" for both boards and be maintained with new releases. Therefore, we chose to simplify our temporary port by excluding the original Portenta C33 board.
    • This is also why, you can't just manually add the variant files, as advised:

      advice / request
      Better instruction would be to use the original Arduino UNOR4 library and add the variant manually.

[santaimpersonator]

Finally, to address the issue of having to rename folders. Here is a work around, using a local installation:

Note: You may run into issues with the FastLED library due to how we added support for our board. The modifications may not be compatible with an Arduino core in a local directory.

• Install the Renesas Arduino core through the Board Manager in the Arduino IDE.
  
• Install our ported Arduino core in a local directory: /home/$USER/Arduino/hardware/
  • This is part of why we didn't include the Portenta C33 in the ported Arduino core. However, I didn't included instructions for the local installation because wasn't able to verify full functionality at the time of the product release.
  • We used the /home/$USER/Arduino/hardware/SparkFun/SFE-Renesas-Arduino_core directory to house our files, with SFE-Renesas-Arduino_core as the extracted folder
• Both installations should now be available in the Arduino IDE:
  

---

A few additional notes:

• Make sure to run the post-install.sh script of the ported core, in the local directory, it is required for the USB drivers and DFU upload of the RA6M5 Thing Plus
• Don't forget these installation steps for the Arduino IDE 2.x.x:

  sudo add-apt-repository universe
  sudo apt install libfuse2

• You may need to add the user to the plugdev group for the DFU upload (requires restart or logout)

  sudo usermod -a -G plugdev $USERNAME

[santaimpersonator]

I have some time to update the Linux instructions with the full directory and plugdev group note. However, I am going to hold off on adding the local installation method for now. I just don't have the time to verify the installation method (i.e. peripheral functionality/compilation, additional library compilation, USB upload/board recognition, etc.) for both cores on all three operating systems.

Note: There is a way to have both the Portenta C33 and RA6M5 Thing Plus in a single Arduino core installation. However, I lost the notes for that (I think I tossed it after we decided, having only the RA6M5 Thing Plus would reduce maintenance and that this was just a temporary instruction set... until our pull request got merged).

[paulvha]

To address the incorrect installation instructions, I followed them on an Ubuntu distro. Our instructions worked fine, with a few caveats:

* The Arduino core versioning number issue, as mentioned above for the legacy version of the Arduino IDE.
  
  * We recommend using the Arduino IDE `v2.x.x` to avoid the issue; otherwise, you'll need to name the folder with the same version number.
  * This will allow you the option to have multiple version folders in the directory. The Arduino IDE will recognize the latest version number, when opened.
    
    * While this doesn't address the renaming issue, it does reduce the need to overwrite files each time.
    * Additionally, it will function with the [changes for the FastLED library](http://docs.sparkfun.com/SparkFun_Thing_Plus_RA6M5/software_overview-arduino/#ws2812-rgb-led)

* We don't include the original `Portenta C33` board in our ported version of the Arduino core. This is an intentional choice we made for the documentation, for several reasons:
  
  * The instructions for our _ported_ Arduino core, are meant to be temporary.
    
    * We are currently waiting on a pull request: [Add SparkFun Thing Plus RA6M5. arduino/ArduinoCore-renesas#290](https://github.com/arduino/ArduinoCore-renesas/pull/290)
    * If the _official_ Arduino core gets updated w/o our pull request, we'd have to update the ported Arduino core. This adds unnecessary maintenance (for the reason below)
  * The Renesas Arduino core relies on linkers for its USB driver installation and board recognition.
    
    * This can be seen here: https://github.com/arduino/ArduinoCore-renesas/tree/main/cores/arduino/tinyusb
    * These files would need to be _"rebuilt"_ for both boards and be maintained with new releases. Therefore, we chose to simplify our _temporary_ port by excluding the original `Portenta C33` board.
    * This is also why, you can't just manually add the variant files, as advised:
      > **advice / request**
      > Better instruction would be to use the original Arduino UNOR4 library and add the variant manually.

Thanks for all the information. I am going to try and let you know.

I added the RA6M5-folder in the variant folder, add to boards.txt the necessary information from the Sparkfun core file to the UNOR4 library, restart the IDE and it compiles and provides output.

It looks like it is sufficient by providing in the boards.txt file :
thingplus_ra6m5.compiler.tinyusb.cflags=-DCFG_TUSB_MCU=OPT_MCU_RAXXX
thingplus_ra6m5.compiler.tinyusb.cxxflags=-DCFG_TUSB_MCU=OPT_MCU_RAXXX

#define OPT_MCU_RAXXX 1403 ///< Renesas RAxxx families

[paulvha]

The reason for using 1.8.16 was issues with Teensy (for the Micromod) With V2.x.x. The V1.x library makes IDE V2.x.x hang during startup. There is a new Teensy V2 library to solve that.

I have followed the instructions ( using IDE V2.3.2. / Ubuntu 22.04)
Installed a clean UNOR4 library (no changes applied for the RA6M5)
Installed a clean Portenta library (version 1.1.0)
created a new folder in the Portenta Libray: 1.2.0
copied the Sparkfun core into it.
Restarted the IDE V2.3.2
If I now select the board I can only choose the RA6M5 (different than your picture). I can not select the portenta as in your feedback, But as I don't have any, it is already better for me.

I think it would be good to either change the instructions to add the UNOR4 library (see previous feedback) and/or add that these instructions are for the V2.x.x Arduino IDE.

regards,
Paul

[santaimpersonator]

The reason you are running into this compiler issue is because, of the linkers I mentioned in a previous comment:

I added the RA6M5-folder in the variant folder, add to boards.txt the necessary information from the Sparkfun core file to the UNOR4 library, restart the IDE and it compiles and provides output.

It looks like it is sufficient by providing in the boards.txt file : thingplus_ra6m5.compiler.tinyusb.cflags=-DCFG_TUSB_MCU=OPT_MCU_RAXXX thingplus_ra6m5.compiler.tinyusb.cxxflags=-DCFG_TUSB_MCU=OPT_MCU_RAXXX

#define OPT_MCU_RAXXX 1403 ///< Renesas RAxxx families

A previously specified, you can't just copy over the board files and add the variant:

• The Renesas Arduino core relies on linkers for its USB driver installation and board recognition.
  • This can be seen here: https://github.com/arduino/ArduinoCore-renesas/tree/main/cores/arduino/tinyusb
  • These files would need to be "rebuilt" for both boards and be maintained with new releases. Therefore, we chose to simplify our temporary port by excluding the original Portenta C33 board.
  • This is also why, you can't just manually add the variant files, as advised:

    advice / request
    Better instruction would be to use the original Arduino UNOR4 library and add the variant manually.

[santaimpersonator]

Not to sound rude, but I feel like parts of my responses were either disregarded, missed, or ignored.

• That said, you are free to do what you like.
  • However, if you continue to do so... this conversation will be moving beyond the scope of our support.
• Otherwise, if you would like to get back on track your can either follow:
  • The instructions we provide in the hookup guide
  • The workaround I mentioned in a previous comment

---

I have followed the instructions ( using IDE V2.3.2. / Ubuntu 22.04)
Installed a clean UNOR4 library (no changes applied for the RA6M5)

I'm not sure why you are insisting on installing the board definition for the Uno R4.

• We have never mentioned that in any of these instructions or the hookup guide.
• Moving forward, I will be disregarding any further conversation about the Uno R4. It does not pertain to the RA6M5 Thing Plus and is outside the scope of our support.

Installed a clean Portenta library (version 1.1.0)
created a new folder in the Portenta Libray: 1.2.0
copied the Sparkfun core into it.
Restarted the IDE V2.3.2
If I now select the board I can only choose the RA6M5 (different than your picture). I can not select the portenta as in your feedback, But as I don't have any, it is already better for me.

I'm glad this solution worked for you, but you just followed the instructions we already provided in the hookup guide. I think, as I previously mentioned... you were utilizing the wrong board definition:

I think it would be good to either change the instructions to add the UNOR4 library (see previous feedback) and/or add that these instructions are for the V2.x.x Arduino IDE.

Regarding your suggestion that we update our instructions to your method (utilizing the Uno R4 board definition/Arduino core), will not be taken into consideration. While this solution works for you; it is no different that replacing the Arduino Renesas core of the Portenta boards... which we already provide instructions for. Additionally, the Portenta boards also utilize the same chipset as the RA6M5 Thing Plus.

[santaimpersonator]

I'm closing this issue for the following reasons:

• Our original instructions in the hookup guide worked for you
• The Uno R4, uses a different chipset; unlike the Portenta boards.

That said.... when I get a chance, I will update the hookup guide for the few extra Linux steps. Additionally, I provide an image for selecting the Arduino Renesas Portenta boards, in the board manager to be extra clear about that step.