Converted Arduino Libraries: Naming and Owning?

1

I’m experimenting with an automatic converter of Arduino IDE libraries, so they are usable in XOD. But, naming is a problem.

The Arduino IDE just has a name for a library: “TFT” or “Adafruit NeoPixel”. With the library is a “properties” file that usually has something for the author. Like “Adafruit” or “Alan Grover”.

XOD has 2 levels for libraries, the author, and then the name. Like “bradzilla84/neopixel” or “xod-dev/wd5500”. And, you can only add libraries with yourself as author (or whichever authors you have the login for).

So, what should we do with libraries that are “direct” conversions? The idea of my automatic-conversion is to use the original Arduino IDE Library (again, for example, Adafruit’s NeoPixel library ) and make a very direct conversion to XOD patches (cf. my first proof-of-concept). Then, we’d hope for some XODer to enhance or wrap it to make it more XOD friendly as necessary (or fix parts that don’t quite work).

I’d like to make it obvious that it is the “XOD conversion” of Adafruit’s library. Which would make it easier to find, and make it more obvious what you are getting. The automatic conversion doesn’t add anything, it just exposes it, so It’s not right to say I’m the author.

On the other hand, it is my fault that it is now a XOD library, and not right to imply that Adafruit is the converter of the XOD version of the library. Adafruit doesn’t want surprise question’s on “their XOD library”.

So, where do we put the converted library? Under my name (because I ran the converter), under your name (because you ran the converter), under Adafruit’s name (because it is just their library in XOD form), under some “xod-converted” name?

If it is not under “Adafruit” as the “owner”, then what’s the library name? We get lucky with the Adafruit Neopixel library, because it’s name is officially, “Adafruit NeoPixel”, and gives good credit to Adafruit. But, not everybody named things that way. For example, my TLC59116 library is called, “arduino-TLC59116” (though the properties calls it just “TLC59116)”. So, it would be nice to credit the owner (which is actually “2splat”, or the author, which is me, “Alan Grover”.

Does that all imply that we should name the library whomever-converted-it/$author-$name (using $author from the properties, but the name should be the expected/common name that you see in the Arduino-IDE, which is the directory name). And that can get a bit long.

As briefly mentioned in forum topic 1485, “Prototype Conversion of Arduino Libraries: Summary and Usage”, the automatic conversion should be a service that anyone can use. But then, the “whomever-converted-it” is xod? Or maybe that let’s us set the author to the real author (but then that might not be quite fair to the real author), or to “xod-converted-for-$realauthor”?

Goals for naming:

  • It’s obvious that it corresponds to a specific Arduino IDE Library, so people can find it and know what it is.
  • It gives credit to the original author.
  • It doesn’t unfairly burden the real author with XOD support by implying they did the conversion.
  • It makes it clear it is a converted library (and thus possibly low-level, and not necessarily XOD style).
  • We anticipate further enhancement using native XOD patches to make a “preferred” library.

The question

  1. Right now, someone has to convert the library themselves, and upload it. So, what’s the library name? In a pattern that we can mechanically produce? As examples, this is my TLC5911C library’s properties, and this is Adafruit’s NeoPixel’s library properties.

  2. If we could do the really right thing, what should be the author-name, and the library name.

  3. And where does the version number go? The Arduino Library’s version number should show. But, the conversion could be done multiple times (bugs in the converter!). So, 2 different versioning numbers.

2

XOD borrows its <owner>/<libname> scheme from GitHub. And there I (nkrkv) can’t make a repo on behalf of a user awgrover regardless of how much credit I want to give. Here is a possible solution:

  • The converter produces just projects and it knows nothing about owners, authors, etc. It produces a project/library with the name inferred from properties name: adafruit-neopixel or tlc59116
  • To clearly explain what the XOD library is the converter might generate a description in form “authorship banner + original description”: “Auto-converted with awxc from Adafruit NeoPixel by Adafruit. Arduino library for controlling single-wire-based LED pixels and strip.” or “Auto-converted with awxc from TLC59116 by Alan Grover. Library for TI TLC59116 (and almost TLC59108) I2C Led Driver chip. ARDUINO 1.5+” (where awxc is some name of your cool tool)
  • The xoder who created the auto-conversion artifact publishes the result on behalf of his XOD username. He can make some adjustments/improvements/fixes and another person can convert the same upstream lib and publish it with another owner name which looks fine to me because someone can loose his interest and another man can pick up a popular library wrapper and go on.

The upstream version number can go to the description as well.

So, does such approach is viable? Am I lost any details?

3

I thought I had replied to this, but I guess not. I was basically going to say the same thing nkrkv did. Use Description to add details of where this came from, don’t try to fit it in the name. Search will include the description.

Posting the results as whoever ran the converter is probably the best option instead of trying to implement something new. as nkrkv noted, different people might come up with different fixes or quit supporting it. Multiple people publishing the same library can be a pain, but there is no work-around with the current setup besides adding it to XOD core where anyone can suggest patches to share with everyone.

4

I attempted to Do The Right Thing. Published: awgrover/adafruitneopixel.

And I screwed it up slightly. Somehow the name isn’t what I intended, should be awgrover/adafruit-neopixel-ll (-ll for low-level).

The project.xod looks like:

{
   "name" : "adafruitneopixel",
   "description" : "awgrover/adafruit-neopixel-ll
Arduino library for controlling single-wire-based LED pixels and strip.

Mechanically converted by https://forum.xod.io/u/awgrover using github.com:awgrover/arduino-2-xod from:\nAdafruit NeoPixel (Adafruit_NeoPixel) by Adafruit. Version 1.1.7
https://github.com/adafruit/Adafruit_NeoPixel",
   "authors" : [
      "awgrover",
      "https://forum.xod.io/u/awgrover",
      "Adafruit",
      "Adafruit <info@adafruit.com>"
   ],
   "version" : "2.0.0",
   "license" : "GPLv3"
}

How does that seem?

5

It looks quite clumsy, but readable enough IMO. It would look much better if our site engine renders the description as Markdown rather than plain text. Will do it soon.