FIRST CAN Device Specifications¶
This document seeks to describe the basic functions of the current FRC® & FTC® CAN system and the requirements for any new CAN devices seeking to work with the system.
Adressage¶
FIRST CAN nodes assign arbitration IDs based on a pre-defined scheme that breaks the ID into 5 components:
Type d’appareil¶
Il s’agit d’une valeur de 5 bits décrivant le type de périphérique adressé. Un tableau des types de dispositif actuellement attribués se trouve ci-dessous. Si vous souhaitez qu’un nouveau type dispositif soit attribué à partir du pool Réservé, veuillez soumettre une demande à FIRST.
Types de dispositif |
|
|---|---|
Diffusion de messages |
0 |
Contrôleur de robot |
1 |
Contrôleur de moteur |
2 |
Contrôleur de relais |
3 |
Capteur gyroscopique |
4 |
Accéléromètre |
5 |
Distance Sensor |
6 |
Encoder |
7 |
Module de distribution d’alimentation (PDP) |
8 |
Contrôleur pneumatique (PCM) |
9 |
Divers |
10 |
Breakout IO |
11 |
Servo Controller |
12 |
Color Sensor |
13 |
Réservé |
14-30 |
Mise à jour du firmware |
31 |
Manufacturier¶
Il s’agit d’une valeur de 8 bits indiquant le fabricant du périphérique CAN. Les valeurs actuellement attribuées se trouvent dans le tableau ci-dessous. Si vous souhaitez avoir un ID de fabricant attribué à partir du pool Réservé veuillez soumettre une demande à FIRST.
Manufacturier |
|
|---|---|
Broadcast |
0 |
NI |
1 |
Limelight |
2 |
FIRST |
3 |
CTR Electronics |
4 |
REV Robotics |
5 |
Grapple |
6 |
MindSensors |
7 |
Team Use |
8 |
Kauai Labs |
9 |
Copperforge |
10 |
Playing With Fusion |
11 |
Studica |
12 |
The Thrifty Bot |
13 |
Redux Robotics |
14 |
AndyMark |
15 |
Vivid Hosting |
16 |
Vertos Robotics |
17 |
SWYFT Robotics |
18 |
Lumyn Labs |
19 |
Brushland Labs |
20 |
Réservé |
21-255 |
API / identificateur de message¶
The API or Message Identifier is a 10-bit value that identifies a
particular command or message type. These identifiers are unique for
each Manufacturer + Device Type combination (so an API identifier that
may be a « Voltage Set » for a REV Robotics Motor Controller may be a
« Status Get » for a CTR Electronics Motor Controller or Current Get
for a CTR Power Distribution Module).
L’identificateur de message est en outre divisé en 2 sous-champs: la classe API 6 bits et l’index API 4 bits.
Classe API¶
The API Class is a 6-bit identifier for an API grouping. Similar messages are grouped into a single API Class. An example of the API Classes for a CAN Motor Controller is shown in the table below.
Classe API |
|
|---|---|
Voltage Control Mode |
0 |
Speed Control Mode |
1 |
Voltage Compensation Mode |
2 |
Position Control Mode |
3 |
Current Control Mode |
4 |
Status |
5 |
Periodic Status |
6 |
Configuration |
7 |
Ack |
8 |
L’index API¶
The API Index is a 4-bit identifier for a particular message within an API Class. An example of the API Index values for a CAN Motor Controller Speed Control API Class is shown in the table below.
L’index API |
|
|---|---|
Enable Control |
0 |
Disable Control |
1 |
Set Setpoint |
2 |
P Constant |
3 |
I Constant |
4 |
D Constant |
5 |
Set Reference |
6 |
Trusted Enable |
7 |
Trusted Set No Ack |
8 |
Trusted Set Setpoint No Ack |
10 |
Set Setpoint No Ack |
11 |
Numéro de périphérique¶
Device Number is a 6-bit quantity indicating the number of the device of a particular type. Devices should default to device ID 0 to match other components of the FIRST Control System. Device 0x3F may be reserved for device specific broadcast messages.
Cadres protégés¶
FIRST CAN Nodes which implement actuator control capability (motor controllers, relays, pneumatics controllers, etc.) must implement a way to verify that the robot is enabled and that commands originate with the main robot controller (i.e. the roboRIO).
Diffusion de messages¶
Les messages de diffusion sont des messages envoyés à tous les nœuds en définissant les champs « Type de dispositif » et « Manufacturier » à 0. La classe API pour les messages de diffusion est 0. Les messages de diffusion présentement définis sont listés dans le tableau ci-dessous:
Description |
|
|---|---|
Disable |
0 |
System Reset |
1 |
System Resume (Reprise du système) |
10 |
Devices should disable immediately when receiving the Disable message (arbID 0). Implementation of other broadcast messages is optional.
These packets are all 0 length packets.
Only Disable is currently sent by Systemcore. The System Reset and System Resume messages are reserved for future use.
These packets are forwarded over Motioncore to all Motioncore buses.
This packet is always sent as a CAN 2.0 frame, it is never sent as an FD frame.
Requirements for FIRST CAN Nodes¶
For CAN Nodes to be accepted for use in the FIRST System, they must:
Communicate using Arbitration IDs which match the prescribed FIRST format:
Utiliser un type de périphérique CAN valide et légal (selon le tableau 1 - Types de périphériques CAN)
Utiliser un ID de fabricant valide et légal (selon le tableau 2 - Codes de fabricant CAN)
Utiliser la (les) classe (s) et index API attribués et documentés par le fabricant du périphérique
Avoir un numéro de dispositif qui peut être choisi par l’utilisateur dans le cas ou plusieurs unités du même type de dispositif sont destinées à coexister sur le même réseau.
Prendre en charge les exigences minimales des messages de diffusion, comme indiqué dans la section Messages de diffusion.
If controlling actuators, utilize a scheme to assure that the robot is issuing commands, is enabled, and is still present.
Provide software library support for C++, and Java or arrange with FIRST® or FIRST’s Control System Partners to provide such interfaces.
Battement de cœur universel¶
The roboRIO provides a universal CAN heartbeat that any device on the bus can listen and react to. This heartbeat is sent every 20 ms. The heartbeat has a full CAN ID of 0x01011840 (which is the NI Manufacturer ID, RobotController type, Device ID 0 and API ID 0x061). It is an 8 byte CAN packet with the following bitfield layout.
Description |
Byte |
Width (bits) |
|---|---|---|
Match time (seconds) |
8 |
8 |
Match number |
6-7 |
10 |
Replay number |
6 |
5 |
FTC Motor Override |
6 |
1 |
Red alliance |
5 |
1 |
Enabled |
5 |
1 |
Autonomous mode |
5 |
1 |
Test mode |
5 |
1 |
System watchdog |
5 |
1 |
Tournament type |
5 |
3 |
Time of day (year) |
4 |
6 |
Time of day (month) |
3-4 |
4 |
Time of day (day) |
3 |
5 |
Time of day (seconds) |
2-3 |
6 |
Time of day (minutes) |
1-2 |
6 |
Time of day (hours) |
1 |
5 |
struct [[gnu::packed]] RobotState {
uint64_t matchTimeSeconds : 8;
uint64_t matchNumber : 10;
uint64_t replayNumber : 5;
uint64_t ftcMotorOverride : 1;
uint64_t redAlliance : 1;
uint64_t enabled : 1;
uint64_t autonomous : 1;
uint64_t testMode : 1;
uint64_t systemWatchdog : 1;
uint64_t tournamentType : 3;
uint64_t timeOfDay_yr : 6;
uint64_t timeOfDay_month : 4;
uint64_t timeOfDay_day : 5;
uint64_t timeOfDay_sec : 6;
uint64_t timeOfDay_min : 6;
uint64_t timeOfDay_hr : 5;
};
If the System watchdog flag is set, motor controllers are enabled. If 100 ms has passed since this packet was received, the robot program can be considered hung, and devices should act as if the robot has been disabled.
Note that all fields except Enabled, Autonomous mode, Test mode, FTC Motor Override and System watchdog will contain invalid values until an arbitrary time after the Driver Station connects.
The FTC Motor Override flag is set when the a motor controller hardware client is allowing enablement of FTC motors without a DS connected. In this state, the robot code will be disabled.