Prototype Conversion of Arduino Libraries: Summary and Usage

[awgrover]

Based on the prototype (forum topic 1471) I did for Adafruit Neopixel library, I have lots of things to discuss.

1. How should I post all the issues? New topics? One big thread? A new category? Commone subject line? The issues concern philosophy of XOD, questions about process (library names), apparent bugs, observations about libraries/abstract-patches, new features, etc. So, some should be of interest to other XODers

2. This will serve as my first “topic”: Summary and Usage

(this has been updated. Please see github for up-to-date text)

Up till now (XOD v0.25.2 2018-11-06), it has required a degree of expertise to make Arduino IDE libraries usable in XOD. This is quite a barrier to using XOD for many projects. For example, XOD does not have the NeoPixel library (@bradzilla84 has a partial one!), and Neopixels are very popular.

I thought it would be possible to automatically generate a XOD library from an Arduino library. The class in the Arduino library becomes the “object” in XOD via the constructor, and each method becomes a node.

I assumed that the result might be a bit crude, and low-level. But, it provides all the features, and a XODer could then make a prettier library around it. If it only gets 80% right, that’s probably good enough to use for many things (and can be manually repaired later). So, automatic conversion could make libraries available faster, and more accessible.

Also, if the XOD library were parallel to the Arduino library, then existing tutorials for the Arduino IDE world would give some idea of how to use them in XOD.

My vision is to see this installed in XOD itself, or in the XOD website. We could build up the libraries quite quickly. As they are auto-converted, we should request refinement/repair/wrapping on the XOD forum!

I chose Adafruit’s NeoPixel V1.1.7 library to try.

Playing With The Auto-converted Neopixel Library

I did not upload it, because it likely has many issues. Also, not really ready for beginners! But you could still try.

The library has the philosophy that you “thread” the patches together with the “object” (the output of the constructor), to get patches to fire in the right order. I think the XOD team prefers a different philosophy (this is another post for discussion!). Anyway, this prototype works like that.

• Manually install the library from github. Back to the stone age:
  • Download the zip (from “download or clone”)
  • Using your archive extractor (i.e. open the .zip), find the xod/__lib__/adafruit directory
  • Copy the directory into your $xoddir/__lib__. On linux it’s ~/xod/__lib__, sadly I don’t know what it is on windows or mac. Sorry.
  • quit and restart XOD
  • You should have the new library!
• Example
  • I have one example built! In the zip you downloaded above, it’s xod/neotest6.xodball. Copy it into your xod directory, or just put it somewhere and open it directly from xod (or import it). It shows setting 2 pixels, with a delay between them.
• Basic usage. Very much like the Arduino IDE.
  • “make” the neopixel object
    • Use the adafruitneopixel patch to represent a single neopixel “string”. Actually, I suppose, it represents “all the neopixels on the same wire on a particular pin”. Because you can chain neopixel devices together.
    • n is the number of “pixels” in the string.
    • p is the pin the string is on. Just like for the Arduino IDE, most digital pins work.
    • t is the RGB order. My neopixel happens to be GRB. Sadly, you have to look in the Adafruit_NeoPixel.h file, find the section that starts with #define NEO_RGB, and find the value that that represents your pixel order, and then convert the hex value to decimal and put that in t. E.g. GRB is 0x52, which is 82 decimal.
  • Put the begin patch in, and link.
    
  • Now add various patches like set-pixel-color, chaining together via the dev outputs.
    • Don’t forget show! Just like in the Arduino IDE.
    • The “methods” from Arduino IDE are patches in XOD.

Examples

I’m working on more examples, copying the Arduino library’s examples. That will be a good further test of what I’ve done. I’ll update my github xod library as I go and add to this thread. Look for examples in xod/ in my github.

Playing With My Converter

Yikes! It’s a hack! clanglib -> python bindings -> python program -> json -> perl.

Super terse instructions: change /home/awgrover as appropriate. Only works on ubuntu linux (lots of hard coded paths inside).

• create the xod library directory (tells you the xod library path): ./ard2xod library /home/awgrover/Arduino/libraries/Adafruit_NeoPixel
• make all the patches: ./ard2xod make /home/awgrover/Arduino/libraries/Adafruit_NeoPixel /home/awgrover/xod/__lib__/adafruit/adafruit-neopixel

I’m going to work on the examples first. Bug me if you want more “how to” sooner.

[awgrover]

Updated. Re-constructed the “simple” example from the arduino library. Added 2 of my own examples to help figure out the “RGB” order. Updated the Summary.

See the github for this stuff.

Presumably, more updates will be announced here.

[nkrkv]

Absolutely amazing! I’m not always able to quickly find enough time for a comprehensive reply to your ideas because they are really wide and very progressive. Takes time to think about them. Sorry for the delays.

I have lots of things to discuss. How should I post all the issues? New topics?

Yes. New topics is the best option I think. XOD forum is not such a big bazaar to think about common subjects, an extra level of grouping or something. I’m thrilled to nake and discuss the issues.

Also, if some behavior is definitely a bug, feel free to issue it directly on GitHub: Issues · xodio/xod · GitHub It will save us a bit of time and make the fix closer.

@awgrover

I assumed that the result might be a bit crude, and low-level. But, it provides all the features, and a XODer could then make a prettier library around it.

I was thinking of the same flow

@awgrover

My vision is to see this installed in XOD itself, or in the XOD website

It uses Python and Clang which are cumbersome (nearly impossible with our resources) to deploy correctly on all the various desktop platforms. A more realistic approach is a web [micro]service (a section of xod.io for example) which takes GitHub URL in and gives a xodball out. XOD IDE could be just another web service client as well.

@awgrover

The library has the philosophy that you “thread” the patches together with the “object” (the output of the constructor), to get patches to fire in the right order. I think the XOD team prefers a different philosophy (this is another post for discussion!)

Start the discussion. I like the threads (also called chaining in other languages) but I would like to find a solution to prevent library authors from thinking, again and again, should they pass an object through or not.

@awgrover

My neopixel happens to be GRB. Sadly, you have to look in the Adafruit_NeoPixel.h file, find the section that starts with #define NEO_RGB , and find the value that that represents your pixel order, and then convert the hex value to decimal and put that in t . E.g. GRB is 0x52, which is 82 decimal.

You can use the Byte type for t and then put the value 52h in it to avoid hex-to-dec conversion.
A possible enumeration implementation is described in XOD XEN F001.

[awgrover]

Updated. Now using pulses to chain/sequence/thread things.

• redid examples. Moved into library space. Added descriptions.
• removed protected properties
• attempted static methods (but clang fail)

See my github, still manual library install.

[awgrover]

Updated. Now uses you as the author. Figured out I needed relative type names. And published the awgrover/adafruitneopixel library (removed from this tools github).