Editor suggestion to aid documentation...

[maitchy]

Just a thought: could the programming editor accept some pseudo-command to aid project documentation... an idea inspired by the old COBOL "environment division" in a way, the aims are:

1. put something in a standard format towards the top of the program that documents how all of the pins are supposed to be used (input, output, grounded, open, connected to a temperature sensor, EEPROM, etc).

2. Use that information to check at compile time for silly mistakes, such as an output to an input pin.

3. Optionally use that information by external programs (or tools accessed from pull-down menus) that might print a picture of the chip and the wiring immediately around it for checking... hopefully the software would be told the type of picaxe chip selected, and might even know the prototype board details). Being an external program, it could be up to developers of projects/boards that use a picaxe to provide something really useful to developers or schools, even to the level of a complete set of instructions on how to wire everything, what to test before switching on, etc... to make it more fool-proof.

4. Ideally, combine this with the "symbol" facility so programmers can simultaneously define a symbol (such as green_led) to either a standard pic pin name (e.g. RA1 or P1A) or a leg name or whatever, and have the value for the symbol change if it needs to if a different picaxe chip is used. Perhaps even allow conditional symbols - assigning particular pins depending on the chip selected... to allow one program to be used with the 08M, 14M or 20M for example.

5. At some stage add to this some of the concepts of libraries or OO - by adding to your library a definition for (say) a DS1820, assigning a pin to this device might make standard routines available for using it (which would only take up memory if used in your program), and would imply appropriate tests on the choice of pin and its IO mode. users should be able to build up libraries for many devices, e.g. a CD4094 (with several pins assigned to the data and clock and optionally other uses) so the programmer can call routines to output complete bytes etc. Obviously the addition of conditionally-linked subroutines is a major addition to the editor, but it could be allowed for as a future step when designing an environment section.

Such a section (which would be too messy as a single-line syntax) might look something like this (with indentation which got lost in posting):

define environment:
author Barney.Rubble@bedrock.net
copyright GPL
version 1.04B
requires:
picaxe 08M or 14M
supply regulated
components:
leds:
green x1
red x1
resistors:
330 ohms x2 "R2..3"
10k x1 "R1"
switch (push on)
pins:
button = in3
green_led = out1 (output)
red_led = out2 (output)
uses:
debounce from switch_routines

end environment

Notice that very little of this would actually be used by the editor - it is mostly a giant multi-line comment (in a particular format) although more and more may be noticed by editor software or external programs as time goes by - e.g. revision control systems, aids to those preparing experiments for classes, etc.

The key is to encourage good documentation (including of the hardware) in a simple way that can be expanded in usefulness later.

Mark

 

[hippy]

#rem .. #endrem will give you want you want.

 

[BCJKiwi]

Or,
View / Options / Use header

 

[maitchy]

Well, *most* of what I want is a comment, so the #rem block will do that, and *some* of those lines will be constant (like author), so "Use header" has some merit, but there is more to it... some connection information that is relevant to software (so a comment is not enough - it would need to feed into the symbol facility for example, and hopefully more later).

To use picaxe chips in simple educational projects you want nice pictures of what should be connected where, and the golden rule in computer systems is that if some documentation has to be manually updated to keep track with reality (in this case: hardware port usage matching software assumptions) then eventually it gets out of sync - better to have interconnection details part of the program, and not just a comment but with some effect. It isn't terribly difficult to do compared with macro assemblers' features of 25 years ago or more... although the degree to which the IO connections are displayed with cute graphics is a question of how much somebody may want to spend on the job.

The other side of the coin is that the picaxe appeals to more serious designers where a single chip can do the work of gluing together main bits of the circuit with less fuss than resorting to specialist chips or assembler code, etc. But it only remains less fuss if there is the support of tools like libraries of code or experience in connecting particular devices in specific ways. At some point maintaining scraps of text files with libraries of routines for accessing various IO devices, and using messy cut-and-paste, will ruin productivity.

Personally, at a minimum, I'd want to be able to specify I'm connecting some serial EEPROM or 1-wire sensor or common shift register; tell it which pins, and have libraries of code ("macros" at least) available that are known to work and will be adjusted to work with the pins I specify. Ideally there'd be some Internet-based database of known devices accessed seamlessly, with routines and accumulated experience stored for most devices. If I need to upgrade to a different picaxe the "environment macro" processor should do as much to make the same code work (or warn that it cannot). This would give the picaxe a big advantage in designs.

The way to implement this with least change to the editor software is to allow an external program to pre-process the source every compile where the program contains the block of information at the start, simply being told the current (assumed) picaxe type plus the source program, and it returns the source to be compiled in the normal way. That processed code would remain during debugging/simulation (when the code cannot be changed anyway), then revert to the typed program when you get to the stage of changing the code next. So this keeps the software editor from being reliant on 3rd party software, yet opens it to new features that could be good for two important types of users - educational and more serious project designers.

 

[hippy]

The current compiler does have a degree of macro processing available with SYMBOL, #DEFINE and #IF while #INCLUDE is planned. Admittedly it's not as comprehensive as a C-style pre-processor.

IMO, the biggest difficulty with applying large-scale programming paradigms and methodologies to the PICAXE and similar devices is their constrained nature. As soon as one gets into complex application design it quickly turns to removing redundant code and optimising. The idea of libraries is a good one but I think they would only be of limited use for PICAXE programming.

I use libraries on other platforms ( Active-X particularly ), but on microcontrollers where it's mainly achieved via #INCLUDE I rarely use a library 'as is' except to check it works as a first step. I invariably have to tune them to what I'd like.

I'm one of those who believes there's only so much which can be done to make a programmer's life easy, and at some point they have to accept that it's their role to get the code right and keep documentation up to date and correct. There may be some mechanism of applying 'design rules' for the Programming Editor to check against, but I think that would be a lot of work to add with little gain for most people.

It would be possible to add an external pre-processing stage but it's not entirely straight forward though. When a compilation occurs some #INCLUDE files will be on disk, some will be open in the editor so different to what's on disk. It may happen but Rev-Ed has curently chosen not to support third-party tools as part of their quality assurance policy.