Support for teensy_ports tool

[ivankravets]

See https://forum.pjrc.com/threads/52525-Teensyduino-1-42-Beta-6

teensy_ports -L

[PaulStoffregen]

This stuff isn't really documented anywhere, so here's a bit of attempt to help...

The old way, and still the default, is teensy_reboot tries to find a Teensy connected to your system and send it the reboot request. This really only works well if you have a single Teensy connected. If you have 2 or more, which one will reboot (so you can program code) is pretty much random.

Using teensy_ports, you can get a list of every Teensy. The list gives you a unique identifier and a human readable description. On Linux the identifiers are sysfs pathnames. On Mac, they're Mac IOKit USB location numbers. On Windows, they're a "path" of numerical hardware addresses.

For example, here is the output of "./teensy_ports -L" with 3 boards connected:

/sys/devices/pci0000:00/0000:00:03.0/0000:02:00.0/usb3/3-2/3-2.4 /dev/ttyACM0 (Teensy++ 2.0) Serial
/sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.1/2-1.2.1.2 /dev/hidraw3 (Teensy 3.5) Audio
/sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.1/2-1.2.1.4 /dev/ttyACM1 (Teensy 3.0) Serial

You can use these identifiers with teensy_reboot. You need to use "-port={identifier} -protocol=Teensy". You'll also want to use "-s" for stand alone mode, where it simply sends the USB message to the board without trying to coordinate with the GUI-based Teensy Loader application.

For example, if you want to reboot the Teensy 3.5 from those 3 lines above, you would use this command:

./teensy_reboot -s -port=/sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.1/2-1.2.1.2 -protocol=Teensy

Teensy Loader (GUI) and teensy_loader_cli are still designed to deal with only 1 Teensy at a time. Someday they may be updated. Until then, the intended usage is to avoid leaving any Teensy in bootloader mode. When you send the reboot message with teensy_reboot, only 1 board should be in bootloader mode, and then Teensy Loader will find and program that board.

If you only use 1 board at a time, you don't need all this new stuff. It's meant to allow using more than 1 Teensy connected to your system, where you can control exactly which board reboots and will be found by Teensy Loader (assuming no others are already in bootloader mode).

Remember, teensy_reboot is not guaranteed to succeed. Because the Teensy has only a single native USB port, its ability to hear the reboot request depends on the code running to be listening to the USB. If you program a Teensy with code that turns off the USB port, or keeps interrupts disabled, or stays in a deep sleep mode, or otherwise interferes with the USB, then teensy_reboot can not communicate with your Teensy. Every board has a Program (not Reset, but Program) button to force is to reboot into programming mode, allowing recovery from bad programs which do not respond to USB communication.

These command line parameters are pretty much undocumented. Well, until now. This message is the documentation!

[ivankravets]

@PaulStoffregen thank you so much for the detailed explanation!!!

[PaulStoffregen]

Teensyduino 1.42 also now comes with a teensy_serialmon program. It is intended to implement "serial monitor" communication with Teensy. You run it with "./teensy_serialmon {identifier}". The communication between teensy_serialmon and an IDE is done on stdin and stdout, and it sends you status messages on @stderr.

Of course you can communicate with Teensy as a serial device, if you have programmed it with the code configured to implement USB serial.

But teensy_serialmon adds many nice features, which are very hard to implement. If you configure the code to implement HID, Audio, MIDI or other modes without Serial, teensy_serialmon can automatically detect these. It also knows how to detect USB device removal and connection. If you have a Teensy programed as Audio, it will connect to the extra emulated serial interface. If you then upload Serial code, it will automatically close the connection when the device disconnects (either a physical unplug or running teensy_reboot), and will be able to reconnect to it using the different protocol for whatever code you have just programmed.

[ivankravets]

It seems that teensy_serialmon is a solution for #6 ?

[PaulStoffregen]

Yes, it solves the serial monitor issue in #6.

Of course you must compile the code with the correct -D args. For Serial, you compile with -DUSB_SERIAL. If you want to give users MIDI, you must change the compiler flags to use -DUSB_MIDI.

After programming, which Teensy begins running the freshly built code, it will turn Teensy's USB port back on. Your PC does USB enumeration to detect the USB device. Then teensy_serialmon can automatically detect which USB option you used and start giving you the communication on its stdin/stdout.

You can leave teensy_serialmon running while programming code. Unlike normal serial usage, where you must close the port, teensy_serialmon does all that internally, even if you program new code with a different USB type!

[mgcrea]

Not sure if this is the proper place to report but the teens_ports cli appears to be hanging on my mac:

update hum looks like it's working fine, was missing the -L flag, sorry for the noise!

$ /Applications/Arduino.app/Contents/Java/hardware/tools/teensy_ports -v
teensy_ports, verbose mode
not already running
socket created
bound to port 28542
USB device add callback
  loc=14130000, vid=16C0, pid=0483, ver=0200, ser=3872730
  actual serailnum=387273
    name: [no_device] (Teensy) Serial
USB device remove callback
Serial add callback
  name=/dev/cu.usbmodem3872730, loc=14130000, vid=16c0, pid=0483, ver=0200
  found prior teensy at this loc, age=0.002
    name: /dev/cu.usbmodem3872730 (Teensy) Serial
Serial remove callback
HID Manager started

Same thing for serialmon:

$ /Applications/Arduino.app/Contents/Java/hardware/tools/teensy_serialmon -v /dev/cu.usbmodem3872730
teensy_serialmon, loc = /dev/cu.usbmodem3872730
USB device add callback
  loc=14130000, vid=16C0, pid=0483, ver=0200, ser=3872730
  actual serailnum=387273
USB device remove callback
Serial add callback
  name=/dev/cu.usbmodem3872730, loc=14130000, vid=16c0, pid=0483, ver=0200
Serial remove callback
HID Manager started

[PaulStoffregen]

What happens when you use Arduino 1.8.5 with Teensyduino 1.42? Can you upload programs from Arduino? If not, please use Teensy Loader's Help > Verbose Info window to capture the log of events.

Everything I see here looks perfectly fine. Looks like Teensy is connected to your Mac and running as a USB serial device. When you press the button on your Teensy, running these should find the device in bootloader mode, and running teensy_loader_cli should be able to program it.

Again, if things aren't working and you want support from me, the path for "official" support involves running Arduino and capturing that event log from the gui version of Teensy Loader.

[mgcrea]

@PaulStoffregen everything is working fine on the Arduino side with 1.8.5&1.42 (upload via teensy-gui), for the teensy_ports I was missing the -L flag and now it works.

Only thing is teensy_serialmon -v /dev/cu.usbmodem3872730 that output nothing though my serial port has activity that I can properly see with miniterm, but I can see in the verbose logs that it correctly reconnects after upload/flash.

[PaulStoffregen]

Only thing is teensy_serialmon -v /dev/cu.usbmodem3872730 that output nothing

Run it like this:

teensy_serialmon 14130000

(or substitute whatever location string teensy_ports actually found)

[PaulStoffregen]

The important point is Teensyduino is moving away from device names like "/dev/cu.usbmodem3872730" and now using location strings which precisely define the actual physical USB port. If you change Tools > USB Type (in Arduino, or whatever equivalent menu/setting PlatformIO provides) to something like Audio or RawHID, the device names are completely differeny but the location string remains the same as long as you're physically plugged into the same USB port (and hub, if using hubs).

[mgcrea]

@PaulStoffregen understood, in my case though I don't have any output either:

• working with Miniterm:

$ make serial
--- Miniterm on /dev/cu.usbmodem3872500  9600,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
! BUTTON: RISING_EDGE
> goMotor: HIGH
> goForwardMotor
! BUTTON: FALLING_EDGE
> stopMotor, position=-26602

• not working with teensy_serialmon (no serial output):

$ /Applications/Arduino.app/Contents/Java/hardware/tools/teensy_ports -L
usb:14130000 /dev/cu.usbmodem3872500 (Teensy) Serial

$ /Applications/Arduino.app/Contents/Java/hardware/tools/teensy_serialmon -v 14130000
teensy_serialmon, loc = 14130000
USB device add callback
  loc=14130000, vid=16C0, pid=0483, ver=0200, ser=3872500
  actual serailnum=387250
USB device remove callback
Serial add callback
  name=/dev/cu.usbmodem3872500, loc=14130000, vid=16c0, pid=0483, ver=0200
Serial remove callback
HID Manager started

[PaulStoffregen]

Try running "teensy_ports -L" (without -v). What does it actually print?

Maybe you need "teensy_serialmon usb:14130000"? The teensy_serialmon program is expecting the same string teensy_ports -L gives you.

[PaulStoffregen]

The stings are different on all 3 platforms, and may change (especially on Macintosh, when/if Apple changes IOKit). The only thing you can assume about the location string is no white space.

[mgcrea]

@PaulStoffregen I can confirm that teensy_serialmon usb:14130000 is properly working, thanks! The -v flag drops any output, not sure if this a bug or not.