Developing a weapon

The weapon protocol is carried out over the light bus. Weapons are unauthenticated devices that use a special series of commands to inform the controller about their status, ammunition usage, and recharging. They are separated from normal devices to make it possible to park the device management module entirely during ATOS/CX combat.

This protocol is intended for use with energy weapons, particularly pulsed energy weapons, that draw power from the battery. It does not currently support weapons that replenish ammunition through other means.

Only one weapon can currently be active at a time.

Sent by weapon
weapon active <K> <C> <L> <T> <M>	The unit has activated the weapon. Display it on the HUD. Parameters: K: kilojoules each shot requires C: capacity of clip (in kJ) L: current level of clip (in kJ) T: current weapon temperature M: maximum weapon temperature This information is primarily used for presenting information on the HUD. It is the weapon's responsibility to determine how to behave when it has overheated, as well as to adapt its current temperature by listening for the `weather` message on the light bus.
weapon info <K> <C> <L> <T> <M>	An update to the weapon status information, restated by already-active weapons. Should be sent periodically to ensure L stays synchronized on the HUD, to show T is changing as the weapon cools down after firing, or to update K, M, or C. (Parameters are as in `weapon active`.)
weapon inactive	The unit has deactivated the weapon. Remove from the HUD and other tracking.
weapon reload	Initiate reload. The controller will automatically feed the weapon ammunition, represented by `weapon charge` messages over the light bus (see below.)
weapon fire <T>	Weapon has fired. Lower controller's internal measure of the weapon's ammo level appropriately and update temperature to T.

Sent by controller to weapon
weapon charge <kJ>	Add kJ to ammunition level. Send `weapon info` to update the HUD's ammo level. As of ATOS/E 12.0.24, ammunition is provided in increments of 2.5 kJ at a rate of twice per second, for a total of 5.0 kW, to avoid overheating.
temperature <T>	The current system temperature is T degrees Celsius. This message is sent passively to all devices if security enhancements are installed.
weather <W> <T>	The current environmental temperature is T degrees Celsius, and the weather type is W. This message is sent passively to all devices if security enhancements are installed. The format of W depends on the version of the weather station reporting; current options are 'wet' and 'dry'.

In addition, there are two private messages sent by the controller to the HUD for updating weapon information; these are weapon-active and weapon-status.

Other light bus messages sent by ATOS

Sent by controller
weapon-active <weapon> <K> <C> <L> <T> <M>	Sent to the HUD over the light bus whenever `weapon active` is received from a weapon, or to the querying device when `devices` is received. The `weapon inactive` message from the weapon will send a variant, `weapon-active 00000000-0000-0000-0000-000000000000` to the HUD, indicating that no weapon is active.
defend	Sent to shield devices only; activates a short-term barrier effect in response to incoming damage. (AutoShield.)
integrity <integrity> <chassis-strength> <max-integrity>	The unit currently has (integrity * 100)% of its health, and may heal up to (max-integrity * 100)% of its health. When the unit is at 100% health, it will have (chassis-strength * 100) hit points. By default, all three values are 1. As of ATOS/E 12.0.9, this message can be triggered by sending `integrity-q` to the controller.
fan <speed>	The current cooler level, on a scale from 0.0 to 1.0.
sentinel-flags <temp-units> <true-shield> <repair-allowed> <true-repair-allowed> <autoshield>	Flags used by the HUD. Sent in response to receiving the `devices` message on the light bus, e.g. by the HUD. New in 12.0.8. Parameters are: temp-units: temperature units to use for display only. 0 = degrees Celsius, 1 = degrees Fahrenheit, 2 = Kelvins. true-shield: whether or not TrueShield is enabled (i.e., projectile damage is ignored while the shield is up.) repair-allowed: whether or not the unit can currently repair itself using nanite autorepair. This is suspended during ARC repair. true-repair-allowed: whether or not the unit can currently repair itself, regardless of whether or not it is currently being repaired by an ARC. autoshield: whether or not AutoShield is enabled (i.e., automatically deploy a short-term barrier in response to incoming projectiles.) If repair-allowed is 0 but true-repair-allowed is 1, then the unit is currently being repaired by an ARC and has self-repair enabled. Otherwise, the values are identical.

Public bus protocols

These elements of the system operate on the public bus channel, i.e. -9999999. Unlike other Companion remote console commands, they cannot be accessed using the unit's individual, serial-based channel.

IFF

Similar to the public bus ping command and the light bus ping command, the identify command requests that ATOS report system information on a provided channel. Units may be requested to identify themselves with the command: identify <channel>

The counterpart to the standard pong reply is identification, for which the syntax is:

identification <integrity> <temperature> <repairing> <serial> <os_name> <os_version> <group_key>

integrity: The system integrity level, representing how much more damage the unit can take before repairs are needed. Ranges from 0 (dead) to 1 (undamaged).
temperature: The CPU temperature, in degrees Celsius.
repairing: Whether or not on-board nanite auto-repair is currently engaged. 0: not repairing; 1: repairing.
serial: The unit's serial number, expressed as an integer.
os_name: The name of the combat system. Either "ATOS/E" or "ATOS/CX".
os_version: The version of the combat system, e.g. "12.0.1"
group_key: The UUID of the unit's active group.

The primary purpose of the IFF protocol is to expedite characterization of a unit by a periodic scanner, such as the ATOS LaserLine heads-up display. (Hence the inclusion of groups.)

Repair

Sent by device
repair start	Disable nanite auto-repair. Initiation of repair process.
repair stop	Re-enable nanite auto-repair (if it was enabled before repair began). Termination of repair process.
repair <amount>	Restore amount system integrity. A value of 1 fully repairs the unit. A variant `identification` message will be sent in response to the repair device, over the public bus channel.
heal <amount>	(ATOS/H) Restore amount health. A value of 100 fully heals a person.

The variant identification message is an abbreviated version of the identification message sent only in response to repair, for tracking repair progress by repair stations such as the ARC. It is sent back on -9999999, and is as follows: identification <integrity>

Dealing damage

ATOS recognizes two forms of damage:

Projectile names. If the name of an object colliding with the unit meets a certain pattern, then damage may be dealt according to the properties of that name. Recognized patterns are listed in the table below.
Collision speed. If the name does not match any recognized pattern, then high-speed collisions will be evaluated based on the relative velocity of the object with which the unit has collided. Because this is a relative calculation, a unit propelled at high speeds may take damage from impacting a stationary object. Only velocities above 20.0 m/s will cause significant damage.

atos:<num>	Deals num points of damage.
meleedamage	Deals a constant 30 points of damage. Used by, e.g., Kojima Industries weapons. (Due to a bug, this was 75 points of damage prior to 12.0.9.)
[AT_DMG]	Deals a constant 30 points of damage. Used by LBA weapons.
vice,<type>,<n>	Deals a variable amount of damage depending on the value of type. Used by VICE weapons. ATOS units are considered infantry (INF), and VICE damage is converted to ATOS damage via a 4.0x multiplier, as VICE infantry can only have up to 25 hit points.
other	The relative velocity of the collision is assessed to determine whether to count the impact as a crash or a projectile hit. If the speed is above 20.0 m/s, then 1/4th of the speed in metres per second is applied as damage; otherwise, 1/16th is applied.

return to develop.ns