teensy3.0 loader code OR documentation

Status
Not open for further replies.
T

texane

Member
Hi,

Thanks for this tiny but great board.

I need to program the TEENSY3.0 from another platform the
GUI loader does not work on. To do so, I would need the
documentation of the loader protocol the TEENSY3.0 comes
pre programmed with. I read through the forum, but it is very
unclear to me what the status of the loader for TEENSY3.0 is,
so I have 3 simple questions:
. is there any documentation (or code, the same too me) available,
that fully allows one to write a loader, and that I might have missed?
. if not, is there a plan to release it soon?
. if not (appl. for the 2 above), what are the reasons?

I find TEENSY3.0 a very interesting board, but not having a full
development chain (incl. the loader) is really an issue to me (like
STM32 discovery kits from ST, for instance). Of course, I know
there are reasons not to release every bit of code, and I am very
interested to know yours.

Thanks for you help,

Fabien.
 
This code is currently the only available documentation. If you can read the code, the protocol is there. It's really a very simple protocol.

http://www.pjrc.com/teensy/beta/load_linux_only.c

This is EXPERIMENTAL and UNSUPPORTED code. It also only works on Linux. Ignore the sections for other operating systems, as they have only the Teensy 2.0 implementation.

Briefly, the protocol is pretty much the same as Teensy 2.0, except 3 changes.

  • The 16 bit address field at the beginning of each transfer is expanded to 32 bits. All addresses must be block-aligned.
  • The block size is 1K, so every transfer is 1028 bytes.
  • (here's the more difficult part) Teensy 3.0 will reject the transfer if it's not ready.

The 3rd point is how Teensy 3.0 achieves dramatically faster upload speeds. With Teensy 2.0, the success or failure of a USB control transaction indicates success or failure of the uploading process. With Teensy 3.0, transfer failure is now used as a handshake.

When sending data to Teensy 3.0, you must not immediately treat an error as a failure. It is now a normal part of the protocol, indicating you must retry the transfer later. Only if you continue to get failures for a sustained length of time can you conclude the upload has failed.

Here's the relevant code. Notice how a failure from usb_control_msg() causes a 10ms delay, and the process is retried. It's only considered an upload error if the transfer continues to fail for longer than the timeout (see the rest of the code for details).

Code: 
int teensy_write(void *buf, int len, double timeout)
{
	int r;

	if (!libusb_teensy_handle) return 0;
	while (timeout > 0) {
		r = usb_control_msg(libusb_teensy_handle, 0x21, 9, 0x0200, 0,
			(char *)buf, len, (int)(timeout * 1000.0));
		if (r >= 0) return 1;
		//printf("teensy_write, r=%d\n", r);
		usleep(10000);
		timeout -= 0.01;  // TODO: subtract actual elapsed time
	}
	return 0;
}
 
Last edited:
Eventually, I plan to update this command line version, test it throughly on all platforms (including the 3 BSD ones) and replace this old one:

http://www.pjrc.com/teensy/loader_cli.html

However, very few people use the command line loader, so this is pretty much at the bottom of my priority list. Likewise for Teensy 2.0, the command line one was updated for all platforms very slowly over a few years. It's a huge amount of work to throughly test it on all those platforms.


I am curious if you'll share some info about which platform you're using and what you're trying to do?
 
Also, I should mention the supported path for using Teensy outside Arduino (eg, from a Makefile) is the GUI-based loader with command line tools which manipulate the GUI loader. See the example makefile in hardware/teensy/cores/teensy3 for an example.

This old command line code pretty much only serves as a reference for the protocol. It is published. My long to-do list is prioritized in terms of things that help the most people. I have a big box full of hardware just wanting for Arduino libraries to be tested and documented, so it's unlikely I'll work on this command line version anytime soon.
 
Last edited:
Hi,

Thank you very much, I will have a look at it during the next
week but it looks very like what I need. I understand testing a
software through different platforms is time involving and that
it is not part of your priorities for now, so I wont ask questions
unless really necessary.

The project I am working is a control system that implies adding
an IO expansion board to the RASPBERRY PI, which does not
necessarly run LINUX (can be a more real time oriented kernel,
depending on the purpose). The RPI ETH is the only interface of
this system, and it should be possible to program the expansion
board from it. If some of the code can be useful for any other
purpose (for instance, the teensy3.0 loader), I will publish it to
the community if you agree, of course.

Thanks again,

Fabien.
 
Status
Not open for further replies.
Back
Top