Delft Students On Software Architecture
  1. Arduino IDE
  2. Cataclysm
  3. Cockpit
  4. Django
  5. Eclipse Che
  6. Flair
  7. Flutter
  8. Gutenberg
  9. Home Assistant
  10. IPFS
  11. Keras
  12. Kotlin
  13. Lila
  14. MAPS.ME
  15. Pandas
  16. Poco
  17. Polymer
  18. PowerShell
  19. PyTorch
  20. React Native
  21. SciPy
  22. Servo
  23. Spring Boot
  24. Terraform
  25. Vim
  26. Zephyr
  27. Zulip

The Arduino IDE

Authors: Pieter Kools, Ivo Wilms, Diwakar Babu, Arkajit Bhattacharya

Table of Contents

  1. Introduction
  2. Stakeholder Analysis
  3. Context View
  4. Development View
  5. Deployment View
  6. Technical Debt
  7. Conclusion
  8. References
  9. Appendix

Introduction

Arduino is an open source electronics platform which uses simple I/O boards and a development environment to interact with the board. Arduino boards are capable of performing multiple functionalities based on the set of instructions sent to the microcontroller. The open-source Arduino software (Arduino IDE) is used to write code (C and C++) and upload it to the board. This is an analysis of the Arduino IDE architecture performed by exploring the full project on GitHub. We have aimed at providing insight into the system from different viewpoints. These viewpoints are defined and explained by Rozanski and Woods in their book Software Systems Architecture, Working with Stakeholders using Viewpoints and Perspectives[5]. First, a context view along with stakeholder analysis is performed, followed by development view, deployment view and finally technical debt.

Stakeholder Analysis

In this section, we identify the stakeholders involved in Arduino. The following table identifies the eleven types of stakeholders as explained by Rozanski and Woods[5.1].

Type Stakeholder Small Description
Acquirers BCMI & Arduino AG Company Massimo Banzi, CEO of the company BCMI (which acquired 100% of the Arduino AG that owns all of the Arduino trademarks), decides the future of the Arduino code[6] (of course with his board members’ approvals).
Assessors Core Developers The Arduino company handles the legal regulations of any project that involves Arduino or using the name “Arduino” [14].
Communicators Arduino, community The Arduino has its own education portal (maintained by the Arduino organization) [7] providing kits (via the Arduino website) with the software (free to download from Github) and tips and knowledge on building and creating projects. People discuss Arduino projects and related code on Forums and StackExchange. YouTube is found to be a medium frequently used by many users to discuss and teach Arduino to beginners.
Developers Core developers, integrators, community The core developers of the Arduino software are Massimo Banzi along with Tom Igoe. The frequent and active contributors and Arduino users also play an important role in developing the Arduino code, but they do not have the permission to directly push or merge their code.
System Administrators Community, Arduino users Users play the role of system administrator.
Suppliers Arduino, Github The software packages can be directly downloaded from the official website and also from Github
Maintainers Core Developers, active contributors The Arduino IDE keeps evolving and it is maintained by the developers and contributors by creating bug fix tasks/issues and creating/handling pull requests.
Production Engineers Core developers The developers of Arduino handle the production releases and run tests on new builds.
Support staff Developers, community, Arduino organization Support team The Arduino company has a team of support staff and communicators provide support for Arduino-based applications on various forums (for example Arduino Forums) and StackExchange.
Testers Core Developers and community Developers and contributors are responsible for running JUnit tests to test the code before a PR is made, merged and officially released.
Users Hobbyists, organizations, Arduino research community groups 152 user groups with each group consisting of more than 100 members are recorded throughout the globe [8]. The applications vary from IOT to wireless applications to Robotics.

Beyond the classification of stakeholders by Rozanski and Woods:

The following stakeholders identified are additional stakeholders who do not match the groups in Rozanski and Woods.

Analyzing the stakeholder’s involvement: Power vs Interest Grid

Mendelow’s power-interest grid [13] is used to classify the groups of stakeholders that should be managed closely. Figure 1 shows that the core developers, active contributors on Github and Arduino community are stakeholders who have both high interest and power. These are the people that actively contribute to and maintain the project and need to be managed closely. Users like teachers, bloggers that use Arduino software without many active contributions show high interest, but have very low power and must be informed well. The dependencies have high interest and minimum power. The reason being, users usually buy Arduino shields which comes with libraries and the user can easily use them without much effort. Other users like TU Delft and GSMA show very high interest in the Arduino development, but provide fewer contributions and therefore are not categorized as active contributors.

\ Figure 1: Power Interest Grid of the Arduino IDE where the interest of the stakeholder is shown on the horizontal axis and the power of the stakeholder is shown on the vertical axis.

Context View

The context view describes the scope and responsibilities of Arduino, i.e. its boundaries in terms of what it does or does not do. To be more precise, it defines the relationships, dependencies and interactions between the Arduino IDE and other external/internal systems, organizations, and people across these boundaries.

Scopes and Responsibilities

The Arduino IDE has a well-defined scope for their system. During the design process, core developers discuss what should be part of the scope for the new version. Some of the scopes for the Arduino’s current versions are:

Context Diagram and the External entities and Interfaces

\ Figure 2: Context View of the Arduino IDE describing the relationships with its environment

A short explanation of some of the components in the context view model is as follows:

-Developers: Massimo Banzi is the main developer and co-founder of Arduino along with Tom Igoe. Additionally, active Github users/developers (for example Christian Maglie, Martino Facchin, David A. Mellis, etc.) have been a part in developing new features and maintaining the code.

-Build Requirements: Java Development Kit 8, Apache Ant, avr-gcc, avr-g++, git, unzip and OS-specific software such as Cygwin for Windows, Homebrew for MacOS and make and OpenJFX for Linux.[2].

-Testing Framework: The Arduino IDE makes use of JUnit4 to perform unit- and system tests. These tests can be executed from an IDE or by executing ant test.

-Target Platforms: The Arduino IDE was built to develop programs/apps for Arduino microprocessors on Windows, MacOS and Linux platforms.

-Communicators: Arduino users (teachers, bloggers and developers) communicate mostly on the dedicated Arduino forums and on Stack Exchange.

-Dependencies: The Arduino IDE has a lot of dependencies as seen here and here (.jar files).

-Language: The Arduino IDE is written in Java and is designed for C/C++ development for Arduino microprocessors.

Development View

Figure 3: High-level architecture of the Arduino IDE.

Figure 3 shows the high-level architecture of the Arduino IDE, consisting of main modules arduino-core, app and build. The functionality of these modules will be explained in the Module organization section, followed by a look into the Common Design Model. The Codeline model then takes a deeper look into the project structure and last, the Stakeholders concerned with Development View are identified.

Module Organization

Figure 4: Module Organization of the Arduino IDE.

Figure 4 shows the various modules of the Arduino IDE and how they relate to each other.

Modules

Dependencies
The project is written in Java and has the following build dependencies:

External dependencies
The arduino-core and app modules both contain a processing.app package containing partially modified classes from the Processing Development Environment (PDE). Every now and then when the PDE project updates, those updates are also manually merged into the copied classes. In an attempt to keep this merging process as simple as possible, Arduino IDE developers attempt to keep the signature of these classes as similar to the original as possible. Modifications to these classes are made to fulfill the need of Arduino IDE specific features.

Common Design Model

Every version of Arduino is found to be similar due to the commonality factor, which is provided by the constraints of the development of the Arduino IDE. The main reason for this is to reduce risk and duplication of effort, in combination with increasing the system’s overall coherence.

Common Processing
The modules arduino-core and app consist of unique packages, including adapted packages from the Processing Development Environment (PDE), which were modified to fit the Arduino IDE’s needs. No processes are shared.

Internationalization
The Arduino community has members from different parts of the world. The i18n translator is used to make the Arduino software more accessible to people who speak different languages.

Standardization of design
The Development policy [15] is well documented in each area of open-source project development such as issue creation, making pull requests and code optimization. This helps developers and contributors to maintain the design standards throughout the projects life. Some design standards of Arduino are as follows:

Customisation of libraries: Certain important libraries are maintained by the developers’ team since they are an essential part of the code. These libraries are contributed by the community and can be seen in the list. Any customized libraries can be sent to the Arduino developer forum for any suggestions or possible inclusion as a new entry.

Codeline model

The codeline models in terms of the source code structure, release process, configuration management, build and testing processes are discussed below.

Figure 5: Source code structure of the app and arduino-core module source directories.

Figure 6: Source code structure of the app module test source directory.

The source code structure in figures 5 and 6 show the main packages and top-level classes used to build and test the Arduino IDE.

Building and Testing
The Arduino IDE is built using Apache Ant in combination with a Java Development Kit (JDK) and OS-specific tools for generating the executable. Building happens through executing ant dist (build and generate distribution zip), ant run (build and start) or ant build (build only) from the command line in the build directory. This effectively executes the Apache Ant build task as defined in build/build.xml. This build task also takes care of dependency management tasks such as downloading dependencies, unpacking dependencies, cloning git repositories and checking SHA hashes of downloaded dependencies (the .sha files are supplied in the repository). The Jenkins Continuous Integration is used to generate hourly builds and beta builds.

The arduino-core module does not contain any tests and the app module contains JUnit4 tests. The ant test command runs these tests. The tests are not very robust: while we tested it the results ranged from 4 to 17 test failures depending on the operating system and whether were spaces in the path. Oddly enough, these tests are not automatically executed when building locally or through the Jenkins CI.

Release Process
Production engineers are majorly responsible for monitoring the releases and also control them on Github. The software release process is not much different from any other projects on Github.

  1. Changes are made on separate branches in a fork of the repository.
  2. Merge request is created by a contributor and eventually checked by the production engineers.
  3. Version number is used to keep track of releases.
  4. Draft release is created with release notes.
  5. Rebase the branch onto master and merge the pull request. When the pull request needs rebasing and the developer who performs the merge does not have write access to the pull request, it is closed and then rebased onto master on another branch and merged from there.

After these steps, the production engineer ensures that the release notes are updated properly. The release takes place after a set of pull requests has been merged.

The Arduino IDE is managed by a small set of developers and contributed to by a larger group of users and developers. Version control is used to document additional features and non-backward compatible changes. Pull requests for such changes are postponed until all changes combined are worth a version bump. Since pull requests are always built and often user-tested before merging to the master branch, the technical integrity of the master branch is maintained (it is nearly always stable). While developers do often discuss features, they less often discuss how they should be implemented. This could be because contributors are doing a good job, but it could also mean that developers mainly care about the final result. The Arduino IDE project does not have any static analysis tools and does not come with a code style template. While most of the code is consistent, there are still quite some inconsistencies (mostly whitespace usage) and the documentation (Javadoc) is poor.

Deployment View

This section summarizes the system requirements and dependencies to successfully run the Arduino IDE. Figure 7 illustrates the deployment view of the Arduino IDE.

Figure 7: Deployment View of the Arduino IDE

Technical Debt

Technical debt is a concept that represents the difference between the actual solution and the ideal solution. Choosing an easy, non-ideal solution that is often faster to implement can seem like a good solution, but it can mean that even more work has to be done in the future when working with this non-ideal solution. In computer science, this includes things such as not writing proper documentation, leaving unused or outdated files/code in the project, not creating proper abstraction layers for components that are subject to change and not writing automated tests for new code. There are several forms of technical debt, some of which are discussed below.

Design Debt

Design debt is created by developers making poor design choices for the system. To analyze a part of the design debt, we have used the static analysis tool PMD to identify code smells.

Code Analysis

PMD helps in identifying five types of code violations : Blocker, Critical, Urgent and Warning violations. As per PMD, there are more than 3500 violations, which made it impossible to analyse all of them. Thus, we reduced the scope to Blocker and Crititical violations, which reduced the number of violations to approximately 200.

Blocker and Critical Issues

We have observed the below mentioned blocker violations :

Most of the blocker issues were related to parameter and function naming conventions. In addition to the above mentioned issues, we found many critical violations like reassigning values to incoming parameters. That said, it has to be mentioned that PMD inspects and compares the code with some often used Java Code style guidelines. A tool such as PMD cannot truly determine how bad code is, it is instead used to ensure that code (and later edits to it) follows certain rules consistently, leading to a consistent code base over time. Another issue which is observed a lot in Arduino code is the lack of documentation and inconsistent code style which makes it difficult to understand all the functionalities. To summarize the above mentioned observations, it can be concluded that the code smell is quite high for the Arduino IDE project.

Issue Analysis

There are multiple issues related to the Arduino IDE. For instance, #6951 proposed that ‘Ctrl+F’ in mac opens the find and replace window and it takes roughly half a second for the cursur to move to the new window. This issue was raised because of a couple of commits(0d50f0b and 65103aa) related to another issue#6603. The issue mentioned was reported as a bug and it is difficult to implement the change in Java. This shows lack of end-to-end testing to find the impact of a change in other functionalities of the IDE which doesn’t really reduce the count of issues as it might lead to another issue. In total, there are 110 open issues related to the Arduino IDE which still needs to be taken care of.

Historical Analysis

We have compared the code for the previous releases of the Arduino IDE(ide-1.0.x and ide-1.5.0.x) using PMD to understand the evolution of the design debt over time. It has been observed that a lot of files were removed and added during the process. As per PMD, the number of violations increased with the newer version (1.5.x). Although this comparison do not mean that there will be more problems in future assuming that both the versions didn’t take code practices in account, it is important for any open source project to follow a coding style which leads to a consistent code base. A static analysis tool could have had an impact on this project as the code quality would have stayed roughly the same which is important for a project like the Arduino IDE with more than 100 contributors.

Documentation Debt

Documentation is of great importance in any project for both developers and users. It is very important for a project like the Arduino IDE since it allows developers to more easily find the code they want to edit and understand how the current code works. With proper documentation, one would have to read less code to understand what’s happening. Proper documentation also makes it easier to compare what some method/function does with what it should do. It is equally important for users as well to understand the installation procedure and navigation of the software which can be made easy only by proper documentation. We have checked issues related to documentation raised in the past and we have observed that the type of issues, i.e. typos and inconsistency in documentation, still remains the same. This follows from our analysis of the issues. Some examples are mentioned below.

Issue Analysis

This section looks into issues related to the documentation about Arduino IDE. There are 105 open issues related to documentation.Thus, the documentation debt seems to be really high. For instance, issue 1055 is about the improper documentation of pins_arduino.h, which is important to meet the needs of custom-designed boards. Another issue in Arduino documentation is the inconsistency of data. There were issues raised regarding the inconsistency in data in the website and the documentation. For example, in Issue #8086, the FPGA chip number was wrongly mentioned in the documentation.

Test Debt

The Arduino IDE consists of two projects: ‘app’ and ‘arduino-core’. The ‘app’ project contains JUnit tests and the ‘arduino-core’ project contains no tests at all. However, since the ‘arduino-core’ project is used by the ‘app’ project, it is indirectly tested. In total, there are 65 tests and some of them may fail based on the Operating system(macOS,Linux or Windows) and its version. The results of running a test with instruction coverage are shown below:

Figure 8: Test Coverage

From the above table, it can be observed that the test coverage for arduino-core is only 15.1% and for app it is only 5.9%. From the observations above, we can conclude that the testing debt for Arduino is very high.

Project Debt

The project debt is quite high for the Arduino IDE as there are 920 open issues and 160 pull requests still to be taken care of. Since the core developers are responsible for testing the pull requests, it becomes nearly impossible to keep track of all the pull requests on time and perform a thorough check before merging them.

Suggestions

To avoid documentation debt, we suggest the contributors to properly document their changes in relevant places. Moreover, core developers should refuse to merge the code if proper documentation is not present. In addition to the above mentioned points, there should not be any inconsistencies in different documents regarding a common topic. The backlog of issues can be a symptom of technical debt which should be considered. Similar to ‘CONTRIBUTING.md’ file which serves as a checklist before contributing to the repository, a file should be added to the repository regarding the code style guidelines which have to be followed for any contribution.

Conclusion

In this chapter the architecture of the Arduino IDE was analyzed using the viewpoints described by Rozanski and Woods in their book Software Systems Architecture, Working with Stakeholders using Viewpoints and Perspectives[5]. The stakeholder view identified the stakeholders involved in the project. The stakeholders were analysed using a Power vs Interest grid which led to the conclusion that stakeholders with highest interest and power include the core developers, active contributors on Github and the Arduino community. In the context view we identified the scope and responsibilities of the Arduino IDE and visualized it in a context diagram which shows the relationships, dependencies and interactions between the Arduino IDE and other external/internal systems, organizations, and people across these boundaries. The context view showed that Arduino has a well-defined scope for their system. The development view discussed the module organisation, common design model and codeline model in detail. The deployment view summarized the system requirements and dependencies to successfully run the Arduino IDE. Finally, the analysis performed in technical debt helped us to understand that there are lots of possible improvements to the project when it comes to code smells, documentation and test coverage.

In conclusion, Arduino is a very interesting project maintained by highly skilled engineers, but it would benefit from more active efforts to reduce the technical debt.

References

1. https://en.wikipedia.org/wiki/Arduino_IDE

2. https://github.com/arduino/Arduino/wiki/Building-Arduino

3. Comparing prototype platforms

4. Arduino Documentation

5. Software Systems Architecture, Working with Stakeholders using Viewpoints and Perspectives by Nick Rozanski and Eoin Woods

5.1. Stakeholders

6. A new era for Arduino begins today

7. Teaching, Inspiring and Empowering!

8. Arduino user groups

9. Story and History of Development of Arduino

10. Arduino authorized distributors

11. Development Policy

12. AUniter and Jenkins

13. Olander, S., & Landin, A. (2005). Evaluation of stakeholder influence in the implementation of construction projects. International journal of project management, 23(4), 321-328.

14. Arduino Policy

15. Development Policy

16. The minimum system requirements for Java 8.0

17. Guide for installating the Arduino IDE on Linux

18. https://github.com/arduino/Arduino

19. Understanding Technical Debt

20. Java Code style guidelines

Appendix

To identify the decision-making process for which PRs get merged and which PRs get accepted, we analyzed some PRs. This appendix describes the key points for that analysis. First a description of what happens for most PRs is given. After that, we will take a closer look at the kind of tradeoffs that need to be decided. We will finish with the reasons a PR can be rejected.

PRs can be divided into two categories: a bugfix fixes a bug, while a feature PR adds a new feature or changes an existing feature. Bugfix PRs are basically always considered, as a bugfix is never undesired. For the feature PRs, the core developers first consider whether they want the feature. They do this by weighing the usefulness of the feature versus how much more the feature would complicate the IDE for new users. There are few PRs that get rejected because of this tradeoff. This is presumably because contributors make an issue (or read existing issues) where they will be told that the feature is not desired before they implement the feature and make a PR for it. Nevertheless, an example of a PR that was rejected because it introduced an unwanted feature is PR #2073.

If the PR isn’t rejected outright, it is iterated upon until the PR is either accepted or rejected. During that iteration, the code is reviewed and tested by the community and the core developers. Based on those reviews and tests, the following steps all happen simultaneously:

If the PR hasn’t been rejected before this point, it will be merged.

Most of these tradeoffs happen on some level for all PRs, but the choice is so clear that it doesn’t really count as a tradeoff. But once every so often, there is a genuine tradeoff and the core developers need to provide guidance to the community in which way they want the project to go. The tradeoffs that we found in our analysis are:

Finally, we will look at some of the reasons why a PR can get rejected.