Discussion on the Wiring API and the new style Includes for libmaple

LeafLabs Garden » Community » Help Us Help You

Discussion on the Wiring API and the new style Includes for libmaple

(36 posts) (6 voices)

Started 3 years ago by crenn
Latest reply from modkit

12 3 Next »

crenn
Moderator

Yesterday I made a lengthy post in this thread after mbolivar said this:

temporarily derailed. the wiring APIs are hella AVR-centric and require changes before they make sense for STM32. it will also be necessary to integrate Make within the IDE before this can happen.

the first changes require coordination with the wiring dev team. what needs to happen is: we read the core Wiring API in detail, come up with changes for other architectures (and backwards compatibility + migration plans for AVR), and get them to agree. they are nice guys who are very receptive to this, but i haven't really had the time to dedicate to this (especially since the libmaple APIs themselves have been in a bit of flux lately). if anyone wants to help, that'd be great. i think this is a great project that needs more love from the community.

as to make: we're going to put Make into Maple IDE as a testing ground, and then port the changes over to Wiring. i've previously rewritten the Wiring IDE build system to use Apache Ant in order to automate and simplify the process of pulling in external dependencies, so (hopefully) the problem should be pretty well-factored into (1) get make into the IDE, (2) port our rules.mk system to Wiring's library (i've got a crude linux-only patch, but Windows terrifies me), (3) add the IDE build system magic to get it working on all three platforms.

The following was my feedback:

With regards to the Wiring API, when I wrote the WireBase/"the new Wire" libraries, I was actually inspired to make it so that it can on any platform. If you take a look at it (with the exception for HardWire), there is currently only 1 dependencies (except for uint8, etc) that is centred on libmaple. And that's making a structure to hold i2c messages. This is the sort of style I think that it should be looking at. Developing a general API which is platform agnostic.
For example GPIO, the primary things are to allow pull up resistors to be used, for the pins to be changed to input or output and for data to be changed on the port. There are other things and that's fine, but these are the basic blocks that should be true for the majority of micro controllers on the market. The thing I don't like about Arduino (not sure if the same is true of Wiring) is how the pull up resistors are enabled. To me, the method used is not good. One of the reasons I like libmaple is due to the fact there is an option to enable it when you call pinMode. So instead of this:

pinMode(42, INPUT); digitalWrite(42, HIGH);

you just have this:

pinMode(42, INPUT_PULLUP);

Just fixing that problem and then users don't need to know that writing a 1 in the PORT register (that is what the first example implies I believe) enables the pull-up resistor. The 2nd method does not require the user to know anything about that particular microcontroller's features/registers, they know that with that command, the pin will be made into an input with the pull-up resistor enabled, the work to do this is minimal in code side.

Also, there is something else which bugs me a little, Arduino (and I believe hence Wiring, but I'm not 100% sure) and Maple is the Print class could be easier to use for some users. For example, I want to write a string with a variable in the middle of it. This is how I need to write it in all IDEs.

SerialPort.print("The ceiling is: "); SerialPort.print(ceiling); SerialPort.println(" cm");

It's simple and a little less complex than using printf:

printf("The ceiling is: %lf cm\r\n", ceiling);

But the query I have is more related to C++ which is the backbone of these projects. C++ can have this:

cout << "The ceiling is: " << ceiling << " cm" << endl;

Now if it were to apply the way I'd think it should, it should be like this:

SerialPort << "The ceiling is: " << ceiling << " cm" << endl;

But it could be used for any type of serial port.

Note these are my current thoughts on how the situation is currently and do not represent the thoughts of leaflabs, arduino, wiring or others. You could keep both methods (since essentially the code is shared between the methods) and requires minimal work to get it to be available.

And just lastly, in Arduino: analogWrite(). Wrong name.

EDIT: Also, can you update the drivers included for Windows 64-bit?

Since the thread was not about discussing the Wiring API, it was requested to be moved outside that thread which I can agree with.

There was also a new blog post on the front page about the new include style that is being implemented in libmaple to keep the code more organised as support for new microcontrollers are added:
http://leaflabs.com/2012/07/libmaple-new-include-style-on-the-way/

I made this comment (which got partially eaten by wordpress):

Had a thought about this over the day and the only thing I’d probably change is how libraries are included. Personally I’d prefer to see:

#include <Libraries\Servo.h>

The primary reason is the look of it. If someone wants to look at the library, they only need to look at the IDE Folder and know that library is stored in the folder and can work out the Servo library is in the folder . To me, it’s something that makes developing for the platform easier for beginners.

What do others think of the current Wiring API? Is there something that annoys them about it? What about the new style includes for libmaple? Feel free to leave feedback in this thread, I'm sure both the Leaflabs staff and the Wiring Staff would be interested in reading it.

Posted 3 years ago #
feurig
Member

I have taken to creating USBserial/Serial based classes and adding a printf. The c++ way of doing streams is just this side of dumb.(imHo)

Posted 3 years ago #
crenn
Moderator

The reason I feel that doing a C++ stream is due to the fact end users do not need to know the symbols needed for printf statements, they could learn, but a few will complain about this. Most likely, any change will result in complaining, but that's the nature of things.

Posted 3 years ago #
siy
Member

As for Print, I think that both approaches might be implemented, but I realize that C++ one is simpler to implement (partially because of significantly reduced functionality comparing to decent version of printf).

As for Wiring API in general: I completely agree that existing API is too Arduino-centric. Moreover, I believe that "pin-based" API is inconvenient in general. This is especially problematic when application is moved from devboard to dedicated hardware. To preserve mapping between pins and other hardware it is necessary to refer to board file for every connection. Another issue which comes from "pin-based" approach is that relation between pin numbers and alternative functions (except, perhaps PWM) is just a black magic for less experienced users. For STM32 with several alternative functions at each pin this is especially problematic, although problems exists for the Arduino as well (usual phrases like "to connect to hardware I2C use pins XX and YY" is a sign of this issue). Finally there is no convenient way to work with groups of the pins and since all pins can be assigned to arbitrary GPIO ports/pins as well as no meaningful way to choose pin numbers so they would be assigned to same port (for performance reasons).

I think that by using a little bit of carefully written C++ templates entire API can be made much more convenient and less error prone. Probably it may even increase performance, reduce code size and significantly improve readability. I'm thinking about this approach for some time and while it still raw and not yet formed into complete solution I may share my thoughts if this presents an interest to others.

Posted 3 years ago #
mbolivar
LeafLabs
Thanks for all the great feedback!

crenn:

And just lastly, in Arduino: analogWrite(). Wrong name.

Heh. Yeah. I brought this up with Hernando Barragán (who invented Wiring). He said "yes, that's my fault". He was an artist and designer first and a programmer/EE second when Wiring was being invented, and so perhaps can be forgiven for the mistake ;). Arduino inherited it when they forked the Wiring code.

But the query I have is more related to C++ which is the backbone of these projects. C++ can have this:

cout << "The ceiling is: " << ceiling << " cm" << endl;

Now if it were to apply the way I'd think it should, it should be like this:

SerialPort << "The ceiling is: " << ceiling << " cm" << endl;

I'm with feurig in finding printf() nicer, but I also agree with you and siy that both approaches could be implemented. This has actually been done on Arduino with the streaming library:

http://arduiniana.org/libraries/streaming/

I personally am not a fan of ostream-style operator overloading, but convenience and familiarity should win here. If someone submits a libmaple patch for this, we'd take it.

Another thing to consider is that printf() isn't cheap; linking in all the code to print floating point correctly burns up a lot of flash. (It's usually better to use iprintf() on microcontrollers for this reason).

siy:

Moreover, I believe that "pin-based" API is inconvenient in general. This is especially problematic when application is moved from devboard to dedicated hardware.

I agree with you about that. However, there's a cool trick for this I learned from Anton Eltchaninov when he added support for the STM32VLDiscovery board: just use an enum to alias PXn to the right pin:
```
/* Save Maple pin order and define aliases */
enum {
PA3, PA2, PA0, PA1, PB5, PB6, PA8, PA9, PA10, PB7, PA4, PA7, PA6, PA5,
PB8, PC0, PC1, PC2, PC3, PC4, PC5, PC13, PC14, PC15, PB9, PD2, PC10,
PB0, PB1, PB10, PB11, PB12, PB13, PB14, PB15, PC6, PC7, PC8, PC9,
PA11, PA12, PA15, PB2, PB3, PB4, PC11, PC12 };
```
That way, people who like numbered pins (I'm one of them) get to keep using them, and people who need to consider port and bit aren't prevented from doing so.

I think it's a useful enough hack for solving the sort of problems you're describing that it's worth using on our boards, though I haven't gotten around to it yet.

Another issue which comes from "pin-based" approach is that relation between pin numbers and alternative functions (except, perhaps PWM) is just a black magic for less experienced users.

Yes, I agree. In the current LeafLabs libmaple tree, we solve this problem on a per-peripheral basis with foo_config_gpios() routines (so there's spi_config_gpios(), adc_config_gpio(), usart_config_gpios_async(), etc.). On STM32s where alternate functions actually need to be programmed in via a separate register (like F2 and F4), having functions like this is necessary for portably setting the GPIO configuration for a peripheral. (These functions get called by e.g. pinMode() and HardwareSPI::begin() for Wirish code).

I think that by using a little bit of carefully written C++ templates entire API can be made much more convenient and less error prone.

I'm very leery of introducing templates (in fact, there's an absolute prohibition on templates in libmaple and Wirish). However, the Wiring developers make pretty heavy use of templates in their code, so I'm going to get overruled. So please do share your thoughts on this!
Posted 3 years ago #
siy
Member

The approach used in new version of libmaple solves the issue from the other end and I believe it will be extremely useful for the idea described below. As I've mentioned above the idea is very raw and not completely thought out. So, basic idea is to have all pins named just like in the trick with the enum used by Anton. But every pin is not just an enum, but an object implemented as a template where all peripherals connected to that pin are included as a part of the specialization. For example (not a code, just an illustration):

GPIOA pin 1 has following functions:
1) GPIOA bit 1
2) ADC12 input 1
3) TIMER2 channel 2
4) External interrupt input

So, PA1 should be defined as something like this:

typedef Pin<GPIO<PORTA,PIN_1>, ADC<ADC1,ADCIN_1>, GPTIMER<TIMER2,TIMER_CH1>, EXTI<AFIO_EXTI_PA, AFIO_EXTI_1>> PinA1;
PinA1 PA1;

Pin<> is actually set of templates with different signatures which cover all variations of peripherals connected to pin. Once particular pin is specialized from template, it can be used like this:

// configure input floating mode
PA1.asAdcIn();
PA1.adc().read();
// configure as GPIO PP
PA1.asPushPull();
PA1.pin().set();
PA1.pin().reset();
PA1.pin().set(1);
PA1.pin().toggle();

// external interrupt source
PA1.asExtInterrupt(EXTI.CHANGE, myInterruptHandler);

// PWM output
PA1.asPWM();
PA1.pwm().set(123);

// Get access to backing timer
PA1.timer(); // actually returns reference to something like HardwareTimer instance but specific to timer type.

1) Since access to all pin functions is done through pin itself, many common errors can be detected at compile time. There is no way to invoke PWM-related functionality if pin does not support it. There is no way to invoke advanced timer functionality if pin is backed by general-purpose timer. And so on and so forth.
2) Since all pins are defined as types, there is no need to have static data for all pins. There even no need to have pre-defined names for all pins. User can use arbitrary name for the pin:

PinA1 MyPowerRegulator;

3) Again since most checks can be done at compile time, code can be as effective as direct access to appropriate registers, no more run-time overhead of digitalWrite() and others.
4) Properly implemented this approach enables use of so called "fluent syntax", i.e. chained calls to references returned by previous call:

PA1.timer().asPWM().withPeriod(1000).withOutput(128);

Beside good readability such a code is more convenient for compiler optimizations.

5) Peripherals which depend of more than one pin can be defined with pins inside them and provide access to these pins:

SPI1.pinMiso(); //returns reference to pin instance connected to MISO pin

Hope this idea present an interest.

Posted 3 years ago #
crenn
Moderator

I've been looking into doing the output stream for the print class and am wanting some ideas about what to do for the equivalent of this:

SerialPort.print(longintergervar, HEX);

The way I think I should be doing it is by using a stream manipulator so that you're doing something like this:

SerialPort << SetBase(HEX) << longintergervar;

But there are 2 problems currently, I don't know how to get that manipulator to hold it's state until at least the next variable or if others think this is not a good method for achieving this.
The other option is how the streaming library achieves it, which is to use a function call to implement it. Such as this:

SerialPort << _BASED(longintergervar, HEX);

or this: (both are valid)

SerialPort << _HEX(longintergervar);

What do others think?

EDIT:

Heh. Yeah. I brought this up with Hernando Barragán (who invented Wiring). He said "yes, that's my fault". He was an artist and designer first and a programmer/EE second when Wiring was being invented, and so perhaps can be forgiven for the mistake ;). Arduino inherited it when they forked the Wiring code.

The question is, can it be changed now to pwmWrite? libmaple uses this name, but also has analogWrite to support 'old' sketches, but it's a minimal change that will free up analogWrite to be used for DACs ;D

Posted 3 years ago #
siy
Member

But there are 2 problems currently, I don't know how to get that manipulator to hold it's state until at least the next variable or if others think this is not a good method for achieving this.

Manipulator does not hold the state, it changes state of the stream instead.

Posted 3 years ago #
crenn
Moderator

That is what I meant (but apparently writing it late at night, didn't word it correctly) but I have an idea on how to implement the manipulators I mentioned previously.
Essentially I'd make a variable within the Print.h class to store the settings (and set it up so you can temporarily change the settings or permanently change them) and the manipulators would modify that.

Posted 3 years ago #
gbulmer
Moderator

cren - a tiny point

The thing I don't like about Arduino (not sure if the same is true of Wiring) is how the pull up resistors are enabled. To me, the method used is not good.

The Arduino pull-up code relies exactly on the way the hardware works.
In Section 14.2.1 "Configuring the Pin" of, e.g. http://www.atmel.com/Images/doc8271.pdf
"If PORTxn is written logic one when the pin is configured as an input pin, the pull-up resistor is activated."

I think Wiring/Arduino would have to jump through hoops to prevent that mechanism working.

But I do agree that it is not clear. IMHO, it would have been better to make it explicit rather than have 'magic' as the way to switch on pullup resistors.

Wiring has pullup() and noPullup() http://wiring.org.co/reference/noPullup_.html
IMHO these are more logical than doing it with a call to pinMode and a list of compound modes (INPUT, INPUT_PULLUP, INPUT_PULLDOWN, OUTPUT, OUTPUT_OPENDRAIN, OUTPUT_2MHZ, OUTPUT_10MHZ, OUTPUT_50MHZ, OUTPUT_OPENDRAIN_2MHZ, etc).
STM32 needs pulldown() too.

I have also sketched out code to make I/O more efficient and 'type-safe'.
I used template classes, and predefined constants to replace the pin table.
It ends up looking like the enum list to the user, with A3, D13, and whatever else makes sense.

Without predefined constants, a problem created for a beginner is the overloaded meaning of '<' and '>'.

IMHO, a bigger source of problems is the error messages generated when the user makes a mistake.

I don't think beginners find PA1.timer().asPWM().withPeriod(1000).withOutput(128); clear.
Is PA1.timer().withPeriod(1000).asPWM().withOutput(128); valid, and does it do the same thing? If not, explain that to a beginner.

Please try your favourite approach, but with a few different simple syntax errors added.
Then try to figure out how much you need to understand to diagnose and fix the error.
I feel that lots of beginners would fail to get past the initial examples because the error messages are so impenetrable.
The cases to worry about are the 'unhappy paths'.

I learned my C before C++ existed. I like printf. But I agree with mbolivar that full printf can be huge.

At least one commercial IDE has options to exclude the floating-point-enabled printf, because it is so big, and use the 'integer' version instead. This seems to have a knock-on effect because the initialisation for the floating-point-enabled printf is different (or that was my theory when I was using the IDE). I don't know what happens when the wrong one is chosen, but IIRC, the IDE couldn't guarantee that the right version was linked into the program.

One of the guiding principles of C and UNIX was 'you don't pay for what you don't use'.
I don't want to pay for a huge printf, if all I am doing is printing an integer. Similarly, I don't want to pay the added complexity of having to choose or configure for the 'right' printf.

Further, I either want an insanely simple I/O system (like print & println) where I can forgive it because it is so simple and easy to learn, or I want it to EXACTLY implement of one of the two standard stream I/O systems (possibly a logical subset), the C approach or C++.

Nor do I want to go digging through source code, or googling words known only to the developers to find the documentation.

Oh, and IMHO 'Maple is not for beginners' is not a good response to my concerns.

Posted 3 years ago #
siy
Member

I don't think beginners find PA1.timer().asPWM().withPeriod(1000).withOutput(128); clear.

Fluent syntax is a convenience, not a mandatory requirement, so it is always possible to write calls one per line and get exactly what we have right now. If beginners can understand and use HardwareTimer, there will be no big difference between existing HardwareTimer and proposed approach. Proposed 'builder pattern'-style method naming is not the most convenient for non-chained calls, but this is just naming, after all it is always possible to use regular 'get/set' naming style.

Is PA1.timer().withPeriod(1000).asPWM().withOutput(128); valid, and does it do the same thing? If not, explain that to a beginner.

This call should be perfectly valid and do the same thing if the same sequence of calls valid for existing HardwareTimer (to be exact - with same timer channel). If the sequence is not valid in most cases it is possible to limit possibility to write incorrect code by returning different type from the method (or even by returning void if call should be last in chain).

I think that proposed approach will be simpler for beginners to understand in particular because of application of operations directly to the objects (i.e. LedPin.set() instead of digitalWrite(LED_PIN)) which is more natural and intuitive IMHO. Also, ability to detect many problems at compile time is also extremely helpful for beginners. It is always simpler to explain to beginners why code does not compile than why successfully compiled and flashed code does not work. With more advanced IDE which has 'live' parsing and smart code completion incorrect code just can't be written.

P.S. The example code chosen by you (direct manipulation of hardware timer) is not the simplest thing to understand for beginners regardless from the used approach.

Posted 3 years ago #
crenn
Moderator

The Arduino pull-up code relies exactly on the way the hardware works.
In Section 14.2.1 "Configuring the Pin" of, e.g. http://www.atmel.com/Images/doc8271.pdf
"If PORTxn is written logic one when the pin is configured as an input pin, the pull-up resistor is activated."

I think Wiring/Arduino would have to jump through hoops to prevent that mechanism working.

But I do agree that it is not clear. IMHO, it would have been better to make it explicit rather than have 'magic' as the way to switch on pullup resistors.

Wiring has pullup() and noPullup() http://wiring.org.co/reference/noPullup_.html
IMHO these are more logical than doing it with a call to pinMode and a list of compound modes (INPUT, INPUT_PULLUP, INPUT_PULLDOWN, OUTPUT, OUTPUT_OPENDRAIN, OUTPUT_2MHZ, OUTPUT_10MHZ, OUTPUT_50MHZ, OUTPUT_OPENDRAIN_2MHZ, etc).
STM32 needs pulldown() too.

That's the primary point that I was making (I actually mention the port register after the examples ;D) is that you know a knowledge of what is happening in the hardware to be able to enable the pull up resister.
While the wiring method is a lot clearer (which is the main point of why I didn't like using digitalWrite to do it), I can't personally see how it's more useful than using pinMode to set the pin up, however I'd agree that it's a method that should be included since even if I can't see the 'point of it', doesn't mean someone else can't. (If you could also give me an example where you need to dynamically change the pull up/down resistors, I'd love to hear it)
Also, I personally wouldn't have some of the PinMode options that you're suggesting, as while beginner users could understand the concepts of open drain(using it to interface with a 5V device) or pull up/down resistors, I can't see many beginners changing the GPIO speed.

As for the IO/pin referencing; you need to remember the target of the actual device, which is to allow beginners to micro-controllers/programming to easily write code (or do copy pasting of parts of code) and hook up an electric circuit quickly and easily. If some users want to use the alternative function, there is a table they can look up for that (The same argument could also be used to say on the board there should be PA3 instead of 0). I feel that users would use a trail and error process to find pins with features than looking at a table or manual.
To me "fluent syntax" is a sort of a mixed thing, I can see it's use, but it's not exactly the most beginner friendly thing.

I learned my C before C++ existed. I like printf. But I agree with mbolivar that full printf can be huge.

<snip>
One of the guiding principles of C and UNIX was 'you don't pay for what you don't use'.
I don't want to pay for a huge printf, if all I am doing is printing an integer. Similarly, I don't want to pay the added complexity of having to choose or configure for the 'right' printf.

Further, I either want an insanely simple I/O system (like print & println) where I can forgive it because it is so simple and easy to learn, or I want it to EXACTLY implement of one of the two standard stream I/O systems (possibly a logical subset), the C approach or C++.

Nor do I want to go digging through source code, or googling words known only to the developers to find the documentation.

I learnt C89 before I learnt C++ (and initially struggled to learn C++ because my mindset was so ingrained in C, and some things I do have a certain C 'ring' to it) and actually prefer to use printf since it's the initial method I learnt and also is a lot more cleaner. However (ignoring code size issues since that has already been discussed) to insert variables into the string, you need to know the symbols, while it's not a hard concept for beginners to learn, it may turn off a few which is why I'm sort of pushing to put in streams. Beginners don't need to know the symbols for a stream, however I am concerned about the use of manipulators (which is why I asked previously for feedback on that topic) since for beginners and people currently using Wiring/Arduino/Maple, it's an entirely new concept.
Additionally, I'm not suggesting taking away .print() and .println(). I'm more thinking that using those as a wrapper for streams and moving the streams do what they were previously doing. The fun thing is, the streaming library does this the opposite way, and gets the stream calls to call .print().

Maple is exactly for beginners, since it provides the capabilities that others need that Arduino couldn't. Such as a small package with multiple USART/UART, SPI, I2C ports and quicker processing.

Posted 3 years ago #
siy
Member

To me "fluent syntax" is a sort of a mixed thing, I can see it's use, but it's not exactly the most beginner friendly thing.

I think that fluent syntax took much more attention that it really deserves. I've mentioned it just as one of the benefits of the proposed approach, not the main goal of the proposal. As long as user don't familiar with the fluent syntax or don't feel a need to use it, fluent syntax can be avoided.

Posted 3 years ago #
gbulmer
Moderator

Over tha last 30 years, I have (tried) teaching Pascal, FORTRAN, BASIC, LISP, C, Ada, awk, Bourne shell scripts, yacc, lex, Smalltalk, C++, Java, Erlang, a little bit of Python, some Scratch, and Aduino+C, to people from 9 to 80+, from utter beginner upto post-graduate level. I know several other languages and systems, but these are ones I've tried teaching.

My view is no one *knows* what the best API looks like, but everyone has an opinion. I have done some ad-hoc analysis, and in general, programmers design poor APIs until they are taught how to design APIs. I believe there is some systematic evidence that programmers design poor interfaces for non-programmers.

I believe there is some evidence for some languages and systems. Simplicity and consistency can help a beginner.

I believe that Alan Kay has written on the FONC mailing list that SmallTalk's object+verb ideas were too hard for young children (which was its target audience), and hence the etoys etc. work. So I feel there is evidence to disagree with the assertion ''... proposed approach will be simpler for beginners to understand in particular because of application of operations directly to the objects (i.e. LedPin.set() instead of digitalWrite(LED_PIN)) which is more natural and intuitive IMHO"

Also, that might be misleading, because the equivalent syntax to analogRead(5); is something like PA5.asADC();
PA5.adc().read();`

Lots of new-programmers were able to do things they wanted to do with some variant of none-OO BASIC, and lots of new-programmers cope with Arduino/Wiring digitalWrite(...), analogRead(...). So there is a little evidence that lack of object.verb is not a big enough problem to the Arduino world to have triggered change.

I have not done a methodical analysis, but my ad hoc experience of working with non-programers is Serial.foo() seemed a bit weird after using digitalWrite(...) analogWrite(...), but folks see it is a chunk of mysterious syntax that has a useful effect. IMHO much of the 'semantics' or 'meaning' of the syntax is in the head of sophisticated users, and 'washes over' many new users for much longer than developers might guess.

IMHO, the less that syntax intrudes, and the simpler and more consistent the syntax, the better.
C++ is more difficult than many laguages because it is a "kitchen sink language", it contains everything but the "kitchen sink" with lots of complexity and variety. People have "religious wars" about the "right way". IMHO, that is a low-value activity. It is better to do something, and if it needs to be 'good', do some experiments and get some evidence then improve it if it needs to be improved.

I believe "Perfect is the enemy of Good Enough".

To repeat part of my earlier post. I feel that API designers should focus on the error messages that end users get when there is a small error, rather than "the best way to package functionality", or insisting that the "IDE makes this easy". IMHO it's better to start with something that is easy to explain, with the least baggage, fewest constraints, and lowest overhead. I feel the IDE should help, but not be a necessity in this case because the language can be used outside of any specific IDE.

I would suggest the process of designing the interface might include:
0. Make the necessary changes to the boards silkscreen to support new users (experienced users can read documentation)
1. In programs, misspell a word so that the syntax completion system gives a list far too long to scroll through.
2. Add or delete a piece of syntax so that the 'smart' IDE recommends the wrong correction.
3. Do some functions in the wrong order to that the program doesn't work at run-time.
etc.
For each source of errors, write a short (no more than one picture and two paragraphs) explanation of what the user is supposed to do. If the set of explanations is longer than two pages, then the explanation of fixes may be getting too long.

I don't feel insisting on an IDE to reduce the chances of a class of errors is adequate because IDEs often introduce new sources of confusion, or lengthen the learning curve (I am not alone in finding Eclipse elephantine, slow, inscrutable and hence irritating).

I find the Arduino/Wiring/Maple colour-change for a correct spelling of 'words' is simple enough to explain to a new user, but IMHO syntax completion is yet another source of confusion for new users.

I believe new users are okay with digitalWrite(13, HIGH);. The complaints from new users I recall are things like 'why is there a ";"?' or 'why does "digitalwrite" not work?', or 'why did you choose "13"?', or 'what is "HIGH"?'

I think they might be okay with D3.digitalWrite(HIGH);, D3.write(HIGH);,D3.high(); or D3 = HIGH; providing the silkscreen of the board says "D3" next to the pin.

But I am not sure how I would explain PA1.pin().set();, or why we should have to spend any time on it.

I assume PA1 would be the silkscreen on the board, or it is instantly inferior to digitalWrite(3, ...).
I assume PA1 means Port A, pin 1.

I also assume that PAn are clustered together, in numeric order. Otherwise IMHO it is a potential source of confusion, and we need to run some experiments to see if it helps enough of the user base to make it worthwhile printing in the limited silkscreen area.

Should I also assume there is some simple, direct information to say that PA1 is, or is not an analogue and PWM pin?

In the first few hours, I don't yet understand why anyone needs to get to grips with the idea that a pin is anything other than a digital, analogue or PWM pin; it seems to be irrelevant detail. It seems to be a small fraction of users who need to use a port. So DA1.pin() seems to be noise, and 1, D1 seems to be enough.

I don't think set() is obvious. IIRC, the word 'set' is one of the most overloaded words in the English language (google "what is the word with the most meanings in English").

It isn't clear that set() might be restricted to (roughly) 5V (or 3.3V), or reset() is (roughly) 0V or ground, and toggle() is 'change to the other value'. Why is it not set(HIGH)?

To me, reset has the connotation of setting it back to its reset state; there is a "reset" button on the silkscreen, so that would seem like a reasonable guess. So reset() might also mean make the pin an input.

I have used the word 'toggle' with a few people and given up. To some folks, 'toggle' is the thing that stops the string in the hood or waistband of a coat being pulled out, or sometimes it is the kind of fastener on a specific style of heavy coat.

Summary:
I don't feel the case for object.verb() syntax has been put in a compelling way for new users.
I haven't understood the case for consuming more silk screen area (which is a precious resource) by using 'PA1' rather than '1' or 'D1'.
I don't feel the benefit of being able to say PA1.pin().set(), PA1.adc().read(), PA1.pwm().set(123) is compelling.
AFAICT, there are a bunch of solutions which are equivalent, and have less syntax, for example digitalWrite(D13, HIGH), analogRead(A5), pwmWrite(D9, 123). Further, to retain the simplicity and approachability of e.g. the Arduino, it needs to be clear on the silkscreen what the pin name implies.

I agree that peripherals which manipulate multi-bit values (e.g. USB, serial, SPI and I2C) have a case for an interface which is not pin-number based.
I agree that for peripherals which might take ASCII, UTF-8, or some related character encoding, there is some value in a 'formatting' mechanism.
I agree that it would be nice to have a type-safe and efficient GPIO programming interface, but I feel it needs to be simple, light-weight, easy to explain and use by a new-programmer, and not tilted towards the experienced developer.
I think it is hard to do these things well, and experiment-based processes yielding evidence are a good approach.

Posted 3 years ago #
mbolivar
LeafLabs

I agree with gbulmer on basically all points, especially these:

I agree that it would be nice to have a type-safe and efficient GPIO programming interface, but I feel it needs to be simple, light-weight, easy to explain and use by a new-programmer, and not tilted towards the experienced developer.

Type-safety is nice, but for us, simplicity is better. This is coming from someone who once led a reading group on TAPL, so please don't write me off as yet another knee-jerk C hacker on this.

Please try your favourite approach, but with a few different simple syntax errors added.
Then try to figure out how much you need to understand to diagnose and fix the error.
I feel that lots of beginners would fail to get past the initial examples because the error messages are so impenetrable.
The cases to worry about are the 'unhappy paths'.

Yes, yes, yes! I'll never forget the first time I saw a compile error related to misuse of std::string. Horrible. Also, don't forget that the IDE tries to parse error messages, and it does so rather stupidly, so forcing it to parse errors involving lengthy templated types might require fixes there, too.

Posted 3 years ago #

RSS feed for this topic

12 3 Next »

Reply »

You must log in to post.