Wireless Upload and Hot/Cold Linking

Note

Wireless Upload requires at least CLI 3.1.4, Kernel 3.1.6, VEXos 1.0.5, and OkapiLib 3.3.12 (if used).

PROS supports wireless upload to the V5 Brain via a V5 Controller. Although there are no special requirements to enable PROS to do this, file transfer speeds are typically unacceptably slow. To solve this issue, PROS has a different method of compiling your project so that the PROS kernel and other infrequently modified code are uploaded once and only the code you regularly modify (e.g. opcontrol.cpp, autonomous.cpp, and initialize.cpp) gets transferred to the V5 wirelessly. We call the code you upload once and never change the “cold image” and the code that changes frequently and gets uploaded every time the “hot image.”

By default, this feature is already enabled in your project’s Makefile:

# Set to 1 to enable hot/cold linking
USE_PACKAGE:=1

PROS will automatically detect when you’re using the same combination of libraries and decide not to re-upload the “cold” code. Verification that the library is present is done with filename and checksum of the file. As a result, if you use the same combination of libraries (cold image), only one copy of the cold image is uploaded to the V5.

Warning

Building with hot/cold linking will prevent you from uploading several programs with mismatched kernel versions. If you attempt to do so, the previously uploaded programs will be deleted from the brain when a different cold package is uploaded. To fix this issue, you can either upgrade the kernel of the non-compatible projects to the one on the V5 Brain or disable hot/cold linking in those other projects by changing line above to USE_PACKAGE:=0.

Large Projects

Projects with large codebases may still take some time to upload even with hot/cold linking. You may be able to reduce the size of your hot image by making part of your project a library so that some code is included in the cold image. To do so, edit the following lines of your project’s Makefile:

# Set this to 1 to add additional rules to compile your project as a PROS library template
IS_LIBRARY:=0
# TODO: CHANGE THIS!
LIBNAME:=libbest
VERSION:=1.0.0
# EXCLUDE_SRC_FROM_LIB= $(SRCDIR)/unpublishedfile.c

Change IS_LIBRARY to 1 and rename the library to something of your choosing. We recommend lib<robot name> or lib<team number> (e.g. lib7701) to be unique enough to avoid cause naming conflicts with other cold images. When compiling, PROS will include this library as part of the cold image. Your library should only contain files you infrequently change so that you do not have to frequently upload the cold image. By default, the Makefile is set up to exclude your project’s opcontrol.cpp, autonomous.cpp, and initialize.cpp files. If you change other files frequently, you can add lines like EXCLUDE_SRC_FROM_LIB+=$(SRCDIR)/myfile.c as needed.

An important caveat is that code that goes into the cold image is not able to link against anything (call functions or use variables) in the hot image. Doing so will result in a linker error - you will be told what’s trying to refer to what in the hot image:

bin/libtheseus.a(lcdselector.cpp.o):(.data.inits+0x0): undefined reference to `auton::allianceInit(auton::color)'

You should refactor your code so that only “hot” code calls “cold” code or include the culprit file in the hot image.

An example of a modified Makefile’s relevant lines is shown below:

# Set to 1 to enable hot/cold linking
USE_PACKAGE=1

# Set this to 1 to add additional rules to compile your project as a PROS library template
IS_LIBRARY:=1
LIBNAME:=libtheseus
VERSION:=1.0.0
# this line excludes opcontrol.c and similar files
EXCLUDE_SRC_FROM_LIB+=$(foreach file, $(SRCDIR)/opcontrol $(SRCDIR)/initialize $(SRCDIR)/autonomous,$(foreach cext,$(CEXTS),$(file).$(cext)) $(foreach cxxext,$(CXXEXTS),$(file).$(cxxext)))
EXCLUDE_SRC_FROM_LIB+=$(SRCDIR)/scripts             # exclude any files in the src/scripts directory
EXCLUDE_SRC_FROM_LIB+=$(SRCDIR)/lcdselector.cpp     # exclude src/lcdselector.cpp

Hot/Cold Linking Troubleshooting

Since hot/cold linking involves ensuring two compiled programs interact consistently, there may be additional runtime issues running in this mode. This section serves as a guide for debugging these sorts of issues.

Generally, if the program appears to be running correctly (i.e. the screen shows), then the compilation mode worked correctly and the error you’re experiencing is likely related to your code’s logic. If your code’s logic runs correctly when not using hot/cold linking, contact us so we may assist in troubleshooting.

If you see a black scren, then PROS did not boot correctly.

  • A global constructor is in an infinite loop or raised an exception.
  • See also troubleshooting steps below

If you see a grey screen, then PROS booted correctly, but is not running your hot image.

  • Delete all user programs, perform a clean build, and upload

If you’re having issues, contact us so we may assist in troubleshooting.