Add guide "Using Arduino-libraries in XOD" #63
Conversation
There was a problem hiding this comment.
I think the title is too general. It’s not about using any Arduino libraries in XOD, it’s about creating wrappers around classes representing hardware modules in existing Arduino libraries.
Can we have a more precise title? Not sure, here are suggestions:
- Wrapping Arduino libraries
- Wrapping hardware Arduino libraries
- Wrapping Arduino libraries’ objects
- Wrapping class-based Arduino libraries
50% reviewed at the moment
|
|
||
| # Using Arduino-libraries in XOD | ||
| Many libraries have already been written for Arduino and they can be included | ||
| into XOD to use the full power of the existing ecosystem. |
|
|
||
| To understand this guide, you have to know how to work with | ||
| [custom types](/docs/guide/custom-types/) and how to write | ||
| [C++ code in XOD](/docs/guide/nodes-for-xod-in-cpp/). Also, you need to have |
There was a problem hiding this comment.
Suggest swapping the order of “C++ code in XOD” and “custom types” since the C++ should be read first
| some experience of working with C++ libraries for Arduino. | ||
|
|
||
| Imagine that we want our Arduino board to turn the built-in led on or off when | ||
| we bring the NFC tag (our travel pass, for example) to it. |
There was a problem hiding this comment.
📜 an NFC tag
Suggest dropping parens. Just embed “such as a travel pass” right into the sentence.
| Imagine that we want our Arduino board to turn the built-in led on or off when | ||
| we bring the NFC tag (our travel pass, for example) to it. | ||
|
|
||
| Picture that we have no XOD library to work with RFID/NFC scanner PN532 |
There was a problem hiding this comment.
Is “Picture that” even correct? I’d better use “imagine” or “consider”.
| we bring the NFC tag (our travel pass, for example) to it. | ||
|
|
||
| Picture that we have no XOD library to work with RFID/NFC scanner PN532 | ||
| ([xod-dev/pn532-nfc](/libs/xod-dev/pn532-nfc)), and try to do it on your own. In |
| #include <Adafruit_PN532.h> | ||
| {{/global}} | ||
|
|
||
| // Adafruit_PN532 class wants to know ports in the moment of instantiating |
| {{/global}} | ||
|
|
||
| // Adafruit_PN532 class wants to know ports in the moment of instantiating | ||
| // but we don't know it at this moment. |
| // Adafruit_PN532 class wants to know ports in the moment of instantiating | ||
| // but we don't know it at this moment. | ||
| // Therefore, we reserve memory to store an instance of the class, | ||
| // and create an instance later: |
| {{ GENERATED_CODE }} | ||
|
|
||
| void evaluate(Context ctx) { | ||
| auto state = getState(ctx); |
There was a problem hiding this comment.
We should have a if (!isSettingUp()) return; as the very first check of the function. Otherwise, memory leaks are possible. Don’t forget to add a reasonable comment about it.
| auto irq = getValue<input_IRQ>(ctx); | ||
|
|
||
| // Create an instance of the class with specifying prepared place to store it | ||
| // using the pointer in parentheses. |
There was a problem hiding this comment.
Too complex sentence. Suggest:
Create a new object in the memory area reserved previously.
| we bring an NFC tag, such as travel pass, to it. | ||
|
|
||
| Consider that we have no XOD library to work with RFID/NFC scanner PN532 | ||
| ([xod-dev/pn532-nfc](/libs/xod-dev/pn532-nfc)), and try to make it on your own. |
There was a problem hiding this comment.
we have
on your own
🤔
| download it, saving users from manual install. | ||
| 3. Create action nodes for the new type that correspond to the functions | ||
| and methods provided by the third-party C++ library. | ||
| 4. Create a quick-start node that reads an NFC tag to solve most common purposes. |
There was a problem hiding this comment.
I'm pretty sure it's either "solve problems" or "serve purposes"
| another branch or edited — make a fork and require it. | ||
| </div> | ||
|
|
||
| This is a special line tells XOD, that this node need a third-party library. |
There was a problem hiding this comment.
this node needs a third-party library?
| to use it. Will it be handy to use a chain of nodes `pn532-device`, `init`, | ||
| `read-uid`, just to know is there any NFC tag near the module? | ||
|
|
||
| Let's simplify the life of both ourselves and the library's consumers, and write |
There was a problem hiding this comment.
I'm not sure the idiom "давайте упростим жизнь себе и ..." can be translated like that.
There was a problem hiding this comment.
"Let's simplify our lives and write an nfc-scanner node that solves most common
tasks with just one node."
Ok? :)
There was a problem hiding this comment.
I'm still not sure. https://www.google.ru/search?q="Let%27s+simplify+our+lives" gives just 6k results 😬
|
Also, I noticed that we have a few conventions that are scattered through the docs or even unwritten.
Should we make a "styleguide" section in our docs? |
brusherru
force-pushed
the
feat-using-ardulibs-in-xod
branch
from
d38125d
to
3ff0b83
Compare
|
@evgenykochetkov @nkrkv check it out, please! |
brusherru
force-pushed
the
feat-using-ardulibs-in-xod
branch
from
3ff0b83
to
89e2858
Compare
docs/guide/README.md
Outdated
| @@ -30,6 +30,7 @@ The most straightforward way to extend XOD and add support for new hardware. | |||
| - [Creating variadic patch nodes](./creating-variadics/) | |||
| - [Creating generic patch nodes](./creating-generics/) | |||
| - [Defining custom types](./custom-types/) | |||
| - [Wrapping Arduino libraries](./using-arduino-libraries-in-xod/) | |||
| first line: | ||
|
|
||
| ```cpp | ||
| #pragma XOR require "https://github.com/adafruit/Adafruit-PN532" |
|  | ||
|
|
||
| 1. `flip-flop` is used to trigger `INIT` only once; | ||
| 2. Open the `gate` to trigger `READ` on each subsequent pulse on the `SCAN`. |
brusherru
force-pushed
the
feat-using-ardulibs-in-xod
branch
from
89e2858
to
612a6a7
Compare
|
@nkrkv fixed |
brusherru
force-pushed
the
feat-using-ardulibs-in-xod
branch
from
612a6a7
to
f96cf21
Compare
The alternative title of the guide: "How to require and use third-party libraries from GitHub" :)
Check out both languages, please, English and Russian.