new API

[Jorge Pinto aka Casainho]

Hello :-)

So, me and Ferando Silva, we were working on API and found the need to
change it...

So, here is:
http://code.google.com/p/bicycleledpov/wiki/BicycleLEDPOVAPI

Today I coded the "Command 1: Get identificacion string" and commited
the changes to SVN.

[kvas_off]

Hi Jorge!

I made some grammar and clarifying corrections there, so I ask for
excuse. :)
And I didn't understand quiet right sentences like 'Read a stream of
bytes from memory'
Maybe it's 'cause I'm the dumbest thing in the world.
Or is it something like 'read a memory block' or 'read a byte string'?

[kvas_off]

Because, as I understand, stream is a stream, it runs like a river
(and, in particular, datastream is like this, too).

[Fernando Silva]

The "stream" idea comes from C#.

Using your words "reading a memory stream" is "reading contiguous and
sequential memory blocks".

[kvas_off]

And what's about output values for ''clear all memory'' command?

[kvas_off]

> The "stream" idea comes from C#.

Well, then I should learn si-sharp... :)

[kvas_off]

May be it was asked many times before...
Should value of memory capacity be in output bytes of 'Command 2: Get
hardware properties'? In KB, perhaps?

[kvas_off]

> Using your words "reading a memory stream" is "reading contiguous and
> sequential memory blocks".
>

Maybe then just 'reading sequence of bytes' is suitable?

[Jorge Pinto aka Casainho]

And what's about output values for ''clear all memory'' command?

You are doing great!! I don't have time to update all information...

Well, that commands returns the value of number of bytes that were erased.

I think that could be a colum with title "description" to give more information about each line... If you can, please add it and put a description from what you know :-)

May be it was asked many times before...

Should value of memory capacity be in output bytes of 'Command 2: Get
hardware properties'? In KB, perhaps?

Oh, I think I forgot to put it on Command 2 - please add it, I think it were that before, please see the older version of the wiki page to understand where it was before.

For example:

/* Size of memory of 32kB */

#define MEMORY_SIZE_BYTE_1                              32
#define MEMORY_SIZE_BYTE_2                              0
#define MEMORY_SIZE_BYTE_3                              0

It's defined on http://code.google.com/p/bicycleledpov/source/browse/trunk/hardware/firmware/BicycleLEDPOV.h for actual EEPROM memory.

> Using your words "reading a memory stream" is "reading contiguous and
> sequential memory blocks".
>
Maybe then just 'reading sequence of bytes' is suitable?

I don't really know - it was Fernando who said like that: "stream ..."

[Fernando Silva]

Yes. Why not :)

[kvas_off]

> > And what's about output values for ''clear all memory'' command?
>

> Well, that commands returns the value of number of bytes that were
> erased.

But if it does clear ALL memory, then command should return (in
theory) value for memory size (capacity) after full erasing via this
command. And you stated only two bytes for it, also you meant it in
bytes, not Kbytes (though two bytes for number of Kbytes aren't enough
either; you're right when you suggest to use 3 bytes for memory size,
such way we could use up to not 64MB, but 16GB!) :) What do we do
about it?

[Jorge Pinto aka Casainho]

You are right :-) -- I would prefer to have the answer in number of
bytes and not number of kbytes. So, for that 16GB, we would use 5 bytes,
right?


> >

[kvas_off]

So, according to 'Read a stream of bytes from memory' and 'Write a
stream of bytes to memory' commands in Base API description, maximum
length of byte stream (sequence) is 64 Kbytes and maximum amount of
usable memory is 4 Gbytes. So big amount of data will be loaded into
(and will be read from) memory portionally via several equal commands,
isn't it?

[Jorge Pinto aka Casainho]

Yes, blocks of no more than 64kbytes, each time.

[kvas_off]

> You are right :-) -- I would prefer to have the answer in number of
> bytes and not number of kbytes. So, for that 16GB, we would use 5 bytes,
> right?

Aaaaeh... Maybe 4GB-maximum and 4 bytes (for memory addresses - too,
as it is stated now) are sufficient and good enough, even for "far
future HD video-on-wheel"? Because 5 bytes reserving addresses for up
to 1 Pbyte (1024 TB) - do you actually need this? But if 32bit address
system isn't sufficient then, yes, 5 bytes then.

[Jorge Pinto aka Casainho]

I am attatching an image of result of command 1.

The "$" is the value 36 (shown in ASCII by cutecom), 36 is the lenght of
the string, including the NULL char.

In the end of the string, the "\0x00" is the NULL char.

[kvas_off]

> > Should value of memory capacity be in output bytes of 'Command 2: Get
> > hardware properties'? In KB, perhaps?
>
>
> Oh, I think I forgot to put it on Command 2 - please add it, I think it were that before, please see the older version of the wiki page to understand where it was before.
>
>
> For example:
>
> /* Size of memory of 32kB */
>
> #define MEMORY_SIZE_BYTE_1 32
> #define MEMORY_SIZE_BYTE_2 0
> #define MEMORY_SIZE_BYTE_3 0
>
> It's defined on http://code.google.com/p/bicycleledpov/source/browse/trunk/hardware/firmware/BicycleLEDPOV.h for actual EEPROM memory.

Then, maybe, 4 or 5 bytes for it too, value in bytes, not Kbytes? Or,
no, because of bad form?

And, please, don't give up flash memories! There's a good article
about them, about its common benefits and limitations:
http://en.wikipedia.org/wiki/Flash_memory
Erasing (for writing) by blocks - it's in its nature. Then, maybe, we
just could use block-formatted data for it:
each file (entry, record) should begins from the beginning of memory's
minimum separately erasable block of bytes; if there is EOF, but
memory's minimum block didn't come to an end, then rest of this block
is filled with '1's ('FF's) - i.e. it is left clear after preliminary
erasing. Preliminary erasing could be done via microcontroller
itself.
For this memory type (flash) 'write' and 'read' commands should have
limitations for minimum chip specific block size.
Should 'Command 2: Get hardware properties' return type of used
memory: flash(1,2,3,4,etc. depends of chip specific block size)/not
flash(obvious EEPROM, 0)?

[kvas_off]

> Because 5 bytes reserving addresses for up
> to 1 Pbyte (1024 TB) -

5 bytes reserve addresses for up to 1 Tbyte, btw. :) Maybe then 5
bytes aren't too much for addresses. But, if there are some
difficulties for communication with usual memory chips - then use 4
bytes. (but 5byte-addresses could be converted to 4byte-addresses via
microcontroller in specific designs)

> Should 'Command 2: Get hardware properties' also return

> type of used memory: flash(1,2,3,4,etc. depends of chip
> specific block size)/not flash(obvious EEPROM, 0)?

'depends on' instead of 'depends of'... :)

[kvas_off]

> > Should 'Command 2: Get hardware properties' also return
> > type of used memory: flash(1,2,3,4,etc. depends of chip
> > specific block size)/not flash(obvious EEPROM, 0)?

At this step we can't use memory cards (SD, MMC) not only because of
difficult interface, but also due to serious shaky loads (and
mechanical spring contacts).
It's a pity because of its cheapness and widespreadness (prevalence).