randosy / jallib Goto Github PK

Continue migration of Master Stef's libs. serial_hardware done, now it's
serial_software !

This library is a software usart implementation. PICs without a built-in
USART module can use serial_software to perform RS232 communications. For
PICs with built-in USART, it's also a nice way to have another one.


Attach file: last version taken from Stef's site:

  http://oase.uci.ru.nl/~mientki/pic-tools/jal/libs2/serial_software.jal


Put in this issue as a reference.

The Maxsonar EZ1 US ranger, from Maxbotix, is a ultra sonic ranger. There
are several other types of MaxSonar rangers, the only differences being the
beam widths. We can thus expect the lib to work on all MaxSonar rangers.

See MaxBotix site: http://www.maxbotix.com/

Ranger results can be accessed through serial, reading analog voltage, or
reading pulse width. I'd see 4 files (nothing being definitive, just some
thoughts) 

 * a common lib, dealing with ranger's common task
 * 3 other libs to access it either via serial, analog or pulse

User may include the common lib, then the access lib he wants. He could
even be able to select more than one access lib.

A script must be created in order to create the release package. Most (all)
operations must be automated, even if lots of exceptions are coded. The
idea is to be able to run it again, and get exactly the same result.

Probably a shell script would do the trick. Or a makefile target. The
problem is not everybody will be able to run it....

> Stef has a automatic generated html page for each of his libraries
> and by converting to the JSG the source of this page is removed. 
> Are we fully aware we're leaving this documentation and choose to 
> document (all?) the functions in the samples?

About HTML doc, we could push JSG a little bit further and standardize
comment above prodecure/funcion. Something ala javadoc. pydoc uses
docstrings, *within* the the function body. Ruby uses the block just above. 

IMHO we should avoid heavy syntax such as "@return" etc... Documentation in
comment should be free text. Maybe we could use existing generator, such as
doxygen.

Finally, this script could create a wiki page, instead of HTML, so it could
be integrate here, in jallib site. Wiki pages are searchable (important
feature).

Seb

> -- .  Example:
> -- .     
> -- .     var sword BHL = -684
> -- .     
> -- .     -- send the signed word to the LCD display
> -- .     -- total field width 6 chars
> -- .     -- with 2 digits behind the decimal point
> -- .     format_sword_dec(LCD_char,BHL,6,2)
> 
> 
> Joep, could you adjust n_tot to indicate the total field width, including
> the decimal point?
> This is more consistent with Python (C?)  %fx.y formatting. 

This Master Stef's lib allows to read/write to PIC's eeprom. Should be
quite fast to integrate.

Should be here in the repos:

  .../include/peripheral/data_eeprom/


Attach file: last version taken from Stef's site:

  http://oase.uci.ru.nl/~mientki/pic-tools/jal/libs2/pic_data_eeprom.jal

While testing modifications of the pic_data_eeprom library a problem with
the compiler came up (again). When adding some 'pragma inline' statements
to some procedures the test program produced weird results.   

Circumvention: omit 'pragma inline' from pic_data_eeprom library.

Issue reported to Kyle.

The pic_data_eeprom libary gives compile time errors with some midrange
PICs like 12F683, 16F690, 16f916. It appears that these PICs have deviating
register names for EEPROM operations. For example EEADDR can be called
EEADRL, and EEDATA can be called EEDAT or EEDATL.

Joep reported that: "I ran into a problem with serial_hw; it turns out that
115k2 is not supported with a 10 MHz crystal by the usart; it has a 8.5%
deviation. The library has a constant max_deviation which is set at 5%, but
this is not checked in all cases."

There are problems while comparing negative and positive constants. This is
prbably a bug in the compiler, and it first need to be fixing before.

As a workaround, you'll need to compute deviation yourself, according to
the datasheet !

Include files are base of all libraries. We need to have them quite stable.
jallib include files are produced by Rob's dev2jal, a script which generate
them from MLAB files. This prevent any nasty typos, etc...

What have been decided, from jallib group:

 * register-subfields are prefixed with a register-prefix
 * by default, as in datasheets, analog IO are enabled
 * ...

There are currently 2 number printing libs:

Stef's format.jal
Joep's print.jal

The first has more advanced features:
- hex and decimal output
- constraining the output to max nr of positions
- fixed-point output for decimal output
- two specific time-formats
- it works on (s)bytes and (s)words.

The second one is more complete:
- binary, decimal and hex output
- works on bits, (s)bytes, (s)words and (s)dwords.

Although there is some overlap, I guess its best for now to add them both.

The question is where to put it into the tree. It's in the same category 
like sw_serial, sw_i2c and delay. I see the last one has it's own 
directory but iirc, there should be a /jal directory for these 'language 
extensions'. 

Joep

Add a new external library for the GP2D02 IR ranger. This is a distance
sensor from Sharp, based on infra-red beams. Protocol is quite basic, using
two pins:

 * you can on a pin1
 * wait a little
 * then read on the other pin2, clocking with pin1 

Datasheet can be found here:
http://www.chipdocs.com/datasheets/datasheet-pdf/Sharp/GP2D02.html

Currently, jalapi extracts and parses comments to create html. This
comments can have "special" chars, that is, developers can use the same
syntax as in google code to organize their comments.

As a consequence, when people write comments without that in mind, it
produces weird, barely unreadable doc... Maybe jalapi should just put
comments as they are in the sources, without any more GC wiki parsing. For
instance, between <pre> tags.

Some PICs of the 18F series, mostly if not only those with USB support have
no simple HS oscillator fuse_def pragma declaration, but only HS_PLL and
HS_USB. For example 18f2450.  Reason: The dev2jal script doesn't always
decypher the description in the .dev file for these chips correctly. 

As a consequence of the missing 'HS' the script which generates the
blink-an-led samples chooses to select the internal oscillator. In
principle nothing wrong with that, but maybe a rather unusual setup for
18Fs.   

Not migration of a specific file; I'll try to make a basic layer in both 
software en hardware_i2c. On top of that, interface to an i2c eeprom.

The compiler generates (sometimes) a garbled hex file and wrong assembly
code for the 18F (reproduceable with a blink-an-led sample for the 18F242).
There may be two issues: 
1. wrong assembly code (e.g. a 'movlb 31' in stead of 'movlb 15' to address
the LATA register)
2. Overlapping addresses (with different contents) in the hex file.
Issue is reported to Kyle with all relevant files (also attached as ZIPfile
here). 

While generating API doc, the order the var/const/func/... are displayed is
not the same as in the source. Because implementation uses dict, the order
can not even be predictable.

Need to keep the order in the source. With a difference, though: private
and public var/const/... must be separated (but order within them must be
kept).

Continue migration of Master Stef's libs. This time, it's about adc
(analog-to-digital converter).

This library handles built-in PIC ADC module. While PICs have different
number of ADC channel, this library handles many target chip and oscillator
frenquencies.

There's a discussion about splitting this lib into different "sub-libs",
according to core (adc_12, adc_14, ...), to prevent "ifs" and make this lib
more efficient. We need to discuss more about this, and for now, we agree
not to change the core content of this lib, that is, keeping "ifs".

Attach file: last version taken from Stef's site:

  http://oase.uci.ru.nl/~mientki/pic-tools/jal/libs2/adc_hardware.jal


Put in this issue as a reference.

Could not get a 18F242 blinking its LED for 2 reasons:
1. The _used_delay() function of the compiler (2.4g) is not reliable for
the 18Fs. Most of the times it doesn't work.
2. The device files use 'pragma inline' for the port functions (using LATx
in stead of PORTx), and the compiler (2.4g) seems to have a problem with
'inline'. When I remove the 'pragma inline' the function is executed correctly

Both problems are reported to JalV2 author. 

I have (temporarily) removed the 'pragma inline' for the 18F devices.
For issue 1. an alternative delay function must be used.

Wayne says:

"""
The html produced by (jalapi ?) does not print multi page docs.
To Print all of the doc you have to select all the text and use 'print
selection'.

Not a big deal but annoying for those of us who print the docs for
reference. 
"""

Continue migration of Master Stef's libs. This time, it's about delays.
This libraries uses the compiler's built-in delay function to provide
delays procedures, whatever the chip/frequency are. Useful...

Not so much to do (at least, that's what I plan...).

Attach file is the last version taken from Stef's site (with its permission):

  http://oase.uci.kun.nl/~mientki/pic-tools/jal/libs2/delay_any_mc.jal

Put in this issue as a reference.

There may be an issue with the specification of RAM in the current device
files (rev 591). There are some PICs with ONLY shared memory. Because the
compiler requires unshared memory for variable allocation for these PICs
all RAM is specified as unshared (after a discussion with Kyle). 
But is seems that _pic_accum MUST be allocated in shared memory. This could
be solved by a splitted RAM specification: a few bytes really shared (for
_pic_isr_w and _pic_accum) and the rest as unshared for variable allocation
(even though this is in reality shared memory).
Kyle is asked for advise.

The compiler doesn't accept more than 4 addresses for a variable. For
example for the 16F59 it fails on:   

var volatile byte _pic_accum shared at {  
     0xE,0x2E,0x4E,0x6E,0x8E,0xAE,0xCE,0xEE }
var volatile byte _pic_isr_w shared at {
     0xF,0x2F,0x4F,0x6F,0x8F,0xAF,0xCF,0xEF }

The console output:

jal 2.4 (compiled Jul 15 2008)
generating p-code
k:/jallib/test/16f59.jal:51: '}' expected (got ',')
k:/jallib/test/16f59.jal:51: variable name expected
k:/jallib/test/16f59.jal:51: unexpected token: "0x8e"
b16f59.jal:26: unknown pragma target: osc
b16f59.jal:26: "osc" not defined
b16f59.jal:26: '=' expected (got 'hs')
b16f59.jal:26: "hs" not defined
b16f59.jal:26: '=' expected (got 'pragma')
b16f59.jal:28: unknown pragma target: wdt
b16f59.jal:28: "wdt" not defined
b16f59.jal:28: '=' expected (got 'disabled')
b16f59.jal:28: '=' expected (got 'enable_digital_io')
b16f59.jal:30: "enable_digital_io" not defined
b16f59.jal:33: "pin_a0" not defined
b16f59.jal:33: '=' expected (got 'var')
b16f59.jal:34: "pin_a0_direction" not defined
b16f59.jal:34: '=' expected (got 'led_direction')
17 errors, 0 warnings

Several device files do not contain a procedure to disable the comparator
module.  This may be cause of pins to remain input, even after calling the
enable_digital_io() procudure.

Applies to several PICS over the whole line (12F, 16F, 18F) 

The omission in the dev2jal script is caused by a deviation in  the naming
of the comparator registers (CM1CON0 and CM2CON0 in stead of CMCON and
CMCON1, CMCOM2, etc).

Example:

{{{
const neg = -2000
const pos = 2000
if neg > pos then
    pragma error
end if
}}}

It always "pragma error"s... More:

{{{
const neg = -2000
if neg < 0 then
    pragma error
end if
}}}

It never pragma error"s.

Add a link to jalapi pages to we can get back to jallib home page

A wiki page, explaining why and what is the *jallib style guide* would help
people integrate future libs. This is part of our basement, a kind-of
recipe everyone should follow.

The initial topic is:

 *
http://tech.groups.yahoo.com/group/jallist/messages/25489?threaded=1&m=e&var=1&t
idx=1

"with a few tests and board file, one could create a lot of samples."

See:
http://groups.google.com/group/jallib/browse_thread/thread/a84aab2fe08b326d


Using tags in test and board files, a script could parse them and
selectively generate jal samples, ready-to-compile.

Probably implemented in jallib wrapper.

A script which would validate (or not) any jal lib/sample, according to the
rules defined in JSG. That would be nice :)

It needs to:

 * ensure headers are parsable (correct field syntax)
 * check rules of thumb. Some are quite impossible, such as verifying
there's no default value... Checking indentation, can also be hard...


This script should print warnings and errors, and honor the return code
status (0: success, !0: errors) so it can be used in scripts.

Hi

I want to write general JAL pieces, preferably in a WIKI. Subjects like:
read-modify-write, the watchdogtimer, PWM, etc. 

Should we set up a separate Wiki for that? Where?

On 16f88, the pwm pin can be selected using "pragma target CCP1MUX RB0" or
"pragma target CCP1MUX RB3", defaulting to RB0.

Setting it to RB3 doesn't seem to work though... See attached file of a
non-working sample.

Since the library itself (pwm_ccp1.jal) isn't aware of pin, I think this
might come device file (or the compiler ?)

We should use a buildbot to auto checkout/update/compile/run tests, so we
can track any problems from the very moment they appear.

I know Cruise Control, but it's overkill: http://cruisecontrol.sourceforge.net/

Buildbot is python based, use a master and several slave. Seems fun:
http://buildbot.net/trac

With a lot of brain work and after many cups of tea, I can now
read data from 2 channels of the ADC of a 18F4420 and then write this data
 to the LCD and USART as well as read and write to and from the data  EEPROM.

{reported by Colin Tallis}

Most of the problems encountered were with the register names for the 18f
chips. Many of these variable names needed to be changed in the existing
include files to bring them in line with the variables given in your device
definition files. 

One difference that took some time to figure out was in the 
PIC_DATA_EEPROM file where an extra line:

asm bcf EECON1_CFGS     (Microchip DS39631A page 85)

was needed to get it to work.

Some problems still remain however and the revised include files are a bit
untidy! .....

Since last include files update (issue:3), "feature libraries" can now
start to be migrated. Cleaning and removing weird deps is also important. 

Starting with serial_hardware.jal, from Stef Mientki. This library handles
hardware usart, thus is very important.

Attach file is the last version taken from Stef's site (with its permission):

  http://oase.uci.kun.nl/~mientki/pic-tools/jal/libs2/serial_hardware.jal

Put in this issue as a reference.

Continue migration of Master Stef's libs. pwm_hardware on the way ! 

This library handles built-in PWM module.

Attach file: last version taken from Stef's site:

  http://oase.uci.ru.nl/~mientki/pic-tools/jal/libs2/pwm_hardware.jal


Put in this issue as a reference.

What steps will reproduce the problem?
1. include a device that has 8 bit ADC (e.g. 16F77)
2. define all constants for ADC_hardware.jal
3. include ADC_hardware.jal

When compiling you will get an error that ADRESH is undefined, which is 
correct, since this is not defined for PICS with an 8bit ADC

What is the expected output? What do you see instead?
JALLIB should take this into account and make the code portable for all 
PICs

What version of the product are you using? On what operating system?
JALv24 / JALLIB unvalidated, version downloaded on 11 october 2008

Please provide any additional information below.

The default fuse bits specifications in the device files may cause problems
with programmers which do not mask off fixed zero and fixed one bits of
specific devices.

Need to have a FAQ wiki page, with for instance:

 * where to find libs: validated, unvalidated, casualties
 * how jallib is licensed: zlib + BSD. Explain what can be done in a
commercial project, how PICs can be distribute, etc...

The builtin _usec_delay() function of the compiler doesn't (always) work
for the 18F series of PIC's. The symptoms are weird. On a test-board with
several LEDs on different ports of the 18F242 the sample blink-an-LED
program which is supposed to get 1 LED blinking shows several other LEDs on
different ports (A. B and C) blinking very fast, others are steady on or
off. There are 2 reasons to suspect the compiler:
1. When the _usec_delay() is replaced by a simple loop not using
_usec_delay() the intended LED blinks, and only that LED.
2. With the 2.5 beta version of the compiler the program works correctly. 

Include files are base of all libraries. We need to have them quite stable.
jallib include files are produced by Rob's dev2jal, a script which generate
them from MLAB files. This prevent any nasty typos, etc...

What have been decided, from jallib group:

 * register-subfields are prefixed with a register-prefix
 * by default, as in datasheets, analog IO are enabled
 * ...

We need to define the SVN structure, that is a hierachy of directories, so
all our libs are sorted and categorized.

(his issue is also a test...:)

Multiple scripts are being created here and there to deal with jallib's
svn, generate tests, etc... One wrapper would be better, so anyone wanting
to use/join jallib would only need this script (+ dependencies...)

This script should handle multiple task:

 * compile (default ?), with -s expand, etc... (compile)
 * compile test (see above) (test)
 * generate test results (testresult)
 * generate jallib API (jalapi)

I was thinking about copycat'ing svn executable, by typing "jallib" (the
wrapper name) then the action (compile/test/...) then action's arguments.

This script will use python.

The 'hello-world_lcd' sample for the 16F88 fails when loaded with Tiny
Bootloader and the 'print_byte_hex()' procedure is used to display the
counter value in hexadecimal format.  

In the device files of some 12-bits core PICs the bits of the option_reg
have wrong offsets.

Applies to 16F506. Other devices to be checked.
Other NMMRs have also to be checked for a similar defect.

What steps will reproduce the problem?
1.
2.
3.

What is the expected output? What do you see instead?


What version of the product are you using? On what operating system?


Please provide any additional information below.

This works okay:
 var sdword f =  -8388609

This also:
   var sdword f = -2109876543
but gives a signed/unsigned warning in compiler v2.4g

.jal 2.4 (compiled Jun  5 2008)
.generating p-code
.print_serial_numbers.jal:105: warning: signed/unsigned mismatch

What steps will reproduce the problem?
1. put pragma  data    0x80-0xFF  in the device file
2. compile a program
3. the compiler will write ASM like:

v__banked                      EQU 1
v__access                      EQU 0
v__pic_state                   EQU 0x0080
v__pic_temp                    EQU 0x0080    ; _pic_state

movwf    v__pic_temp,v__access

What is the expected output? What do you see instead?

The compiler uses the PORTA location for temporary variables


What version of the product are you using? On what operating system?

jal 2.4 on Mac OSX 10.4

Please provide any additional information below.

removing the data area in the device file helps

We have an 'unvalidated' and a 'validated' directory tree.
We need a description of the process for moving from unvalidated to
validated, answering at last the following questions:
  1 what the criteria for moving a file from un_ to validated?  
  2 who checks/decides if the criteria are met?
  3 when a file is validated how about updates/bug fixes?

When doc is embedded in a release package, links to samples should point to
a  local file, not the remote SVN browser

The compiler (version 2.4g) does not support PICs with have only shared
memory (no unshared memory).

Currently applies to 12F629, 12F675, 16F630, 16F676.

Temporary(?) circumvention: the device files specify memory as non-shared.  

This is probably only an optimisation issue (unneeded bank switching).