syntax = "proto3"; /* * Meshtastic protobufs * * For more information on protobufs (and tools to use them with the language of your choice) see * https://developers.google.com/protocol-buffers/docs/proto3 * * We are not placing any of these defs inside a package, because if you do the * resulting nanopb version is super verbose package mesh. * * Protobuf build instructions: * * To build java classes for reading writing: * protoc -I=. --java_out /tmp mesh.proto * * To generate Nanopb c code: * /home/kevinh/packages/nanopb-0.4.0-linux-x86/generator-bin/protoc --nanopb_out=/tmp -I=app/src/main/proto mesh.proto * * Nanopb binaries available here: https://jpa.kapsi.fi/nanopb/download/ use nanopb 0.4.0 */ option java_package = "com.geeksville.mesh"; option optimize_for = LITE_RUNTIME; import "portnums.proto"; option java_outer_classname = "MeshProtos"; /* * a gps position */ message Position { /* * The old (pre 1.2) position encoding sent lat/lon as sint32s in field 7,8. * Do not use to prevent confusing old apps */ reserved 7, 8; /* * The new preferred location encoding, divide by 1e-7 to get degrees * in floating point */ sfixed32 latitude_i = 1; sfixed32 longitude_i = 2; /* * This is a special 'small' position update for lat/lon. * It encodes a signed 16 bit latitude in the upper 2 bytes, and a signed longitude in the lower 16 bits. * It is not currently implemented, but can be added in an automatically backwards compatible way later. * Note: ONLY microlatlon OR latitude_i, longitude_i are populated in any particular position. * A microdelta is always relative to the last received full position. * * fixed32 microlatlon = 3; */ /* * In meters above MSL */ int32 altitude = 3; /* * 1-100 (0 means not provided) */ int32 battery_level = 4; /* * This is usually not sent over the mesh (to save space), but it is sent * from the phone so that the local device can set its RTC If it is sent over * the mesh (because there are devices on the mesh without GPS), it will only * be sent by devices which has a hardware GPS clock. * seconds since 1970 */ fixed32 time = 9; } /* * Broadcast when a newly powered mesh node wants to find a node num it can use * Sent from the phone over bluetooth to set the user id for the owner of this node. * Also sent from nodes to each other when a new node signs on (so all clients can have this info) * * The algorithm is as follows: * when a node starts up, it broadcasts their user and the normal flow is for all * other nodes to reply with their User as well (so the new node can build its nodedb) * If a node ever receives a User (not just the first broadcast) message where * the sender node number equals our node number, that indicates a collision has * occurred and the following steps should happen: * * If the receiving node (that was already in the mesh)'s macaddr is LOWER than the * new User who just tried to sign in: it gets to keep its nodenum. We send a * broadcast message of OUR User (we use a broadcast so that the other node can * receive our message, considering we have the same id - it also serves to let * observers correct their nodedb) - this case is rare so it should be okay. * * If any node receives a User where the macaddr is GTE than their local macaddr, * they have been vetoed and should pick a new random nodenum (filtering against * whatever it knows about the nodedb) and rebroadcast their User. * * A few nodenums are reserved and will never be requested: * 0xff - broadcast * 0 through 3 - for future use */ message User { /* * A globally unique ID string for this user. In the case of * Signal that would mean +16504442323, for the default macaddr * derived id it would be !<8 hexidecimal bytes> */ string id = 1; /* * A full name for this user, i.e. "Kevin Hester" */ string long_name = 2; /* * A VERY short name, ideally two characters. Suitable for a tiny OLED screen */ string short_name = 3; /* * This is the addr of the radio. Not populated by the phone, * but added by the esp32 when broadcasting */ bytes macaddr = 4; } /* * A message used in our Dynamic Source Routing protocol (RFC 4728 based) */ message RouteDiscovery { /* * The list of nodenums this packet has visited so far */ repeated fixed32 route = 2; } /* *A Routing control Data packet handled by the routing plugin */ message Routing { /* * A failure in delivering a message (usually used for routing control messages, but might be provided in addition to ack.fail_id to provide * details on the type of failure). */ enum Error { /* * This message is not a failure */ NONE = 0; /* * Our node doesn't have a route to the requested destination anymore. */ NO_ROUTE = 1; /* * We received a nak while trying to forward on your behalf */ GOT_NAK = 2; TIMEOUT = 3; /* * No suitable interface could be found for delivering this packet */ NO_INTERFACE = 4; /* * We reached the max retransmission count (typically for naive flood routing) */ MAX_RETRANSMIT = 5; /* * No suitable channel was found for sending this packet (i.e. was requested channel index disabled?) */ NO_CHANNEL = 6; /* * The packet was too big for sending (exceeds interface MTU after encoding) */ TOO_LARGE = 7; } oneof variant { /* * A route request going from the requester */ RouteDiscovery route_request = 1; /* * A route reply */ RouteDiscovery route_reply = 2; /* * A failure in delivering a message (usually used for routing control messages, but might be provided * in addition to ack.fail_id to provide details on the type of failure). */ Error error_reason = 3; /* * Deprecated - this has been replced with error_reason == NONE && request_id != 0 * This is an ack. * This packet is a requested acknoledgement indicating that we have received * the specified message ID. This packet type can be used both for immediate * (0 hops) messages or can be routed through multiple hops if dest is set. * Note: As an optimization, recipients can _also_ populate a field in payload * if they think the recipient would appreciate that extra state. * * fixed32 success_id = 4; */ /* * Deprecated - this has been replced with error_reason !== NONE && request_id != 0 * This is a nak, we failed to deliver this message. * * fixed32 fail_id = 5; */ } } /* * (Formerly called SubPacket) * The payload portion fo a packet, this is the actual bytes that are sent * inside a radio packet (because from/to are broken out by the comms library) */ message Data { /* * Formerly named typ and of type Type */ PortNum portnum = 1; /* * Required */ bytes payload = 2; /* * Not normally used, but for testing a sender can request that recipient * responds in kind (i.e. if it received a position, it should unicast back it's position). * Note: that if you set this on a broadcast you will receive many replies. */ bool want_response = 3; /* * The address of the destination node. * This field is is filled in by the mesh radio device software, application * layer software should never need it. * RouteDiscovery messages _must_ populate this. Other message types might need * to if they are doing multihop routing. */ fixed32 dest = 4; /* * The address of the original sender for this message. * This field should _only_ be populated for reliable multihop packets (to keep * packets small). */ fixed32 source = 5; /* * Only used in routing or response messages. Indicates the original message ID that * this message is reporting failure on. (formerly called original_id) */ fixed32 request_id = 6; } /* * A packet envelope sent/received over the mesh * only payloadVariant is sent in the payload portion of the LORA packet. * The other fields are either not sent at all, or sent in the special 16 byte LORA header. */ message MeshPacket { /* * The priority of this message for sending. Higher priorities are sent first * (when managing the transmit queue). * This field is never sent over the air, it is only used internally inside of a local device node. * API clients (either on the local node or connected directly to the node) * can set this parameter if necessary. * * (values must be <= 127 to keep protobuf field to one byte in size. * * Detailed background on this field: * * I noticed a funny side effect of lora being so slow: Usually when making * a protocol there isn’t much need to use message priority to change the order * of transmission (because interfaces are fairly fast). * But for lora where packets can take a few seconds each, it is very important * to make sure that critical packets are sent ASAP. * In the case of meshtastic that means we want to send protocol acks as soon as possible * (to prevent unneeded retransmissions), we want routing messages to be sent next, * then messages marked as reliable and finally ‘background’ packets like periodic position updates. * * So I bit the bullet and implemented a new (internal - not sent over the air) * field in MeshPacket called ‘priority’. * And the transmission queue in the router object is now a priority queue. */ enum Priority { /* * Treated as Priority.DEFAULT */ UNSET = 0; MIN = 1; /* * Background position updates are sent with very low priority - * if the link is super congested they might not go out at all */ BACKGROUND = 10; /* * This priority is used for most messages that don't have a priority set */ DEFAULT = 64; /* * If priority is unset but the message is marked as want_ack, * assume it is important and use a slightly higher priority */ RELIABLE = 70; /* * Ack/naks are sent with very high priority to ensure that retransmission * stops as soon as possible */ ACK = 120; MAX = 127; } /* * The sending node number. * Note: Our crypto implementation uses this field as well. See * docs/software/crypto.md for details. * FIXME - really should be fixed32 instead, this encoding only hurts the ble link though. */ fixed32 from = 1; /* * The (immediatSee Priority description for more details.y should be fixed32 instead, this encoding only * hurts the ble link though. */ fixed32 to = 2; /* * (Usually) If set, this indicates the index in the secondary_channels table that this packet * was sent/received on. If unset, packet was on the primary channel. * A particular node might know only a subset of channels in use on the mesh. Therefore channel_index * is inherently a local concept and meaningless to send between nodes. * Very briefly, while sending and receiving deep inside the device Router code, this field instead * contains the 'channel hash' instead of the index. This 'trick' is only used while the payloadVariant is * an 'encrypted'. */ uint32 channel = 3; /* * Internally to the mesh radios we will route SubPackets encrypted per * docs/software/crypto.md. However, when a particular node has the correct * key to decode a particular packet, it will decode the payload into a SubPacket protobuf structure. * Software outside of the device nodes will never encounter a packet where * "decoded" is not populated (i.e. any encryption/decryption happens before reaching the applications) * The numeric IDs for these fields were selected to keep backwards compatibility with old applications. */ oneof payloadVariant { Data decoded = 4; bytes encrypted = 5; } /* * A unique ID for this packet. Always 0 for no-ack packets or non broadcast * packets (and therefore take zero bytes of space). Otherwise a unique ID for * this packet, useful for flooding algorithms. * ID only needs to be unique on a _per sender_ basis, and it only * needs to be unique for a few minutes (long enough to last for the length of * any ACK or the completion of a mesh broadcast flood). * Note: Our crypto implementation uses this id as well. See docs/software/crypto.md for details. * FIXME - really should be fixed32 instead, this encoding only * hurts the ble link though. */ fixed32 id = 6; /* * The time this message was received by the esp32 (secs since 1970). Note: * this field is _never_ sent on the radio link itself (to save space) Times * are typically not sent over the mesh, but they will be added to any Packet * (chain of SubPacket) sent to the phone (so the phone can know exact time of reception) */ fixed32 rx_time = 7; /* * *Never* sent over the radio links. Set during reception to indicate the SNR * of this packet. Used to collect statistics on current link quality. */ float rx_snr = 8; /* * If unset treated as zero (no forwarding, send to adjacent nodes only) * if 1, allow hopping through one node, etc... * For our usecase real world topologies probably have a max of about 3. * This field is normally placed into a few of bits in the header. */ uint32 hop_limit = 10; /* * This packet is being sent as a reliable message, we would prefer it to arrive * at the destination. We would like to receive a ack packet in response. * Broadcasts messages treat this flag specially: Since acks for broadcasts would * rapidly flood the channel, the normal ack behavior is suppressed. Instead, * the original sender listens to see if at least one node is rebroadcasting this * packet (because naive flooding algorithm). If it hears that the odds (given * typical LoRa topologies) the odds are very high that every node should * eventually receive the message. So FloodingRouter.cpp generates an implicit * ack which is delivered to the original sender. If after some time we don't * hear anyone rebroadcast our packet, we will timeout and retransmit, using the regular resend logic. * Note: This flag is normally sent in a flag bit in the header when sent over the wire */ bool want_ack = 11; /* * The priority of this message for sending. * See MeshPacket.Priority description for more details. */ Priority priority = 12; } /* * Shared constants between device and phone */ enum Constants { /* * First enum must be zero, and we are just using this enum to * pass int constants between two very different environments */ Unused = 0; /* * From mesh.options * note: this payload length is ONLY the bytes that are sent inside of the radiohead packet * Data.payload max_size:240 */ DATA_PAYLOAD_LEN = 240; } /* * The bluetooth to device link: * * Old BTLE protocol docs from TODO, merge in above and make real docs... * * use protocol buffers, and NanoPB * * messages from device to phone: * POSITION_UPDATE (..., time) * TEXT_RECEIVED(from, text, time) * OPAQUE_RECEIVED(from, payload, time) (for signal messages or other applications) * * messages from phone to device: * SET_MYID(id, human readable long, human readable short) (send down the unique ID * string used for this node, a human readable string shown for that id, and a very * short human readable string suitable for oled screen) SEND_OPAQUE(dest, payload) * (for signal messages or other applications) SEND_TEXT(dest, text) Get all * nodes() (returns list of nodes, with full info, last time seen, loc, battery * level etc) SET_CONFIG (switches device to a new set of radio params and * preshared key, drops all existing nodes, force our node to rejoin this new group) * * Full information about a node on the mesh */ message NodeInfo { /* * the node number */ uint32 num = 1; /* * The user info for this node */ User user = 2; /* * This position data will also contain a time last seen */ Position position = 3; /* * Returns the Signal-to-noise ratio (SNR) of the last received message, * as measured by the receiver. Return SNR of the last received message in dB */ float snr = 7; /* * Returns the last measured frequency error. * The LoRa receiver estimates the frequency offset between the receiver * center frequency and that of the received LoRa signal. This function * returns the estimates offset (in Hz) of the last received message. * Caution: this measurement is not absolute, but is measured relative to the * local receiver's oscillator. Apparent errors may be due to the * transmitter, the receiver or both. \return The estimated center frequency * offset in Hz of the last received message. * int32 frequency_error = 6; * enum RouteState { * Invalid = 0; * Discovering = 1; * Valid = 2; * } * Not needed? * RouteState route = 4; * Our current preferred node node for routing - might be the same as num if * we are adjacent Or zero if we don't yet know a route to this node. */ uint32 next_hop = 5; } /* * Error codes for critical errors * * The device might report these fault codes on the screen. * If you encounter a fault code, please post on the meshtastic.discourse.group * and we'll try to help. */ enum CriticalErrorCode { None = 0; /* * A software bug was detected while trying to send lora */ TxWatchdog = 1; /* * A software bug was detected on entry to sleep */ SleepEnterWait = 2; /* * No Lora radio hardware could be found */ NoRadio = 3; /* * Not normally used */ Unspecified = 4; /* * We failed while configuring a UBlox GPS */ UBloxInitFailed = 5; /* * This board was expected to have a power management chip and it is missing or broken */ NoAXP192 = 6; /* * The channel tried to set a radio setting which is not supported by this chipset, * radio comms settings are now undefined. */ InvalidRadioSetting = 7; /* * Radio transmit hardware failure. We sent data to the radio chip, but it didn't * reply with an interrupt. */ TransmitFailed = 8; /* We detected that the main CPU voltage dropped below the minumum acceptable value */ Brownout = 9; } /* * Unique local debugging info for this node * Note: we don't include position or the user info, because that will come in the * Sent to the phone in response to WantNodes. */ message MyNodeInfo { /* * Tells the phone what our node number is, default starting value is * lowbyte of macaddr, but it will be fixed if that is already in use */ uint32 my_node_num = 1; /* * Note: this bool no longer means "we have our own GPS". * Because gps_operation is more advanced, but we'd like old phone apps * to keep working. So for legacy reasons we set this flag as follows: * if false it would be great if the phone can help provide gps coordinates. * If true we don't need location assistance from the phone. */ bool has_gps = 2; /* * # of frequencies that can be used (set at build time in the device flash image). Note: this is different from max_channels, this field * is telling the # of frequency bands this node can use. (old name was num_channels) */ uint32 num_bands = 3; /* * The maximum number of 'software' channels that can be set on this node. */ uint32 max_channels = 15; /* * Deprecated! ONLY USED IN DEVICE CODE (for upgrading old 1.0 firmwares) DO NOT READ ELSEWHERE. * The region code for my radio (US, CN, etc...) * Note: This string is deprecated. The 1.0 builds populate it based on the * flashed firmware name. But for newer builds this string will be unpopulated * (missing/null). For those builds you should instead look at the new * read/write region enum in UserSettings * The format of this string was 1.0-US or 1.0-CN etc.. Or empty string if unset. */ string region = 4 [deprecated = true]; /* * TBEAM, HELTEC, etc... */ string hw_model = 5; /* * 0.0.5 etc... */ string firmware_version = 6; /* * An error message we'd like to report back to the mothership through analytics. * It indicates a serious bug occurred on the device, the device coped with it, * but we still want to tell the devs about the bug. * This field will be cleared after the phone reads MyNodeInfo * (i.e. it will only be reported once) * a numeric error code to go with error message, zero means no error */ CriticalErrorCode error_code = 7; /* * A numeric error address (nonzero if available) */ uint32 error_address = 8; /* * The total number of errors this node has ever encountered * (well - since the last time we discarded preferences) */ uint32 error_count = 9; /* * How long before we consider a message abandoned and we can clear our * caches of any messages in flight Normally quite large to handle the worst case * message delivery time, 5 minutes. Formerly called FLOOD_EXPIRE_TIME in the * device code */ uint32 message_timeout_msec = 13; /* * The minimum app version that can talk to this device. Phone/PC apps should * compare this to their build number and if too low tell the user they must * update their app */ uint32 min_app_version = 14; /* * FIXME - add more useful debugging state (queue depths etc) */ } /* * Debug output from the device. * * To minimize the size of records inside the device code, if a time/source/level is not set * on the message it is assumed to be a continuation of the previously sent message. * This allows the device code to use fixed maxlen 64 byte strings for messages, * and then extend as needed by emitting multiple records. */ message LogRecord { /* * Log levels, chosen to match python logging conventions. */ enum Level { UNSET = 0; CRITICAL = 50; ERROR = 40; WARNING = 30; INFO = 20; DEBUG = 10; TRACE = 5; } string message = 1; /* * Seconds since 1970 - or 0 for unknown/unset */ fixed32 time = 2; /* * Usually based on thread name - if known */ string source = 3; /* * Not yet set */ Level level = 4; } /* * Packets from the radio to the phone will appear on the fromRadio characteristic. * It will support READ and NOTIFY. When a new packet arrives the device will BLE notify? * It will sit in that descriptor until consumed by the phone, * at which point the next item in the FIFO will be populated. */ message FromRadio { /* * In the <1.2 versions packet had ID 2, to prevent confusing old apps with our new packets, we've changed */ reserved 2; /* * In the <1.2 versions nodeinfo had ID 4, to prevent confusing old apps with our new packets, we've changed */ reserved 6; /* * The packet num, used to allow the phone to request missing read packets from the FIFO, * see our bluetooth docs */ uint32 num = 1; oneof payloadVariant { MeshPacket packet = 11; /* * Tells the phone what our node number is, can be -1 if we've not yet joined a mesh. * NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. */ MyNodeInfo my_info = 3; /* * One packet is sent for each node in the on radio DB * starts over with the first node in our DB */ NodeInfo node_info = 4; /* * set to send debug console output over our protobuf stream */ LogRecord log_record = 7; /* * sent as true once the device has finished sending all of the responses to want_config * recipient should check if this ID matches our original request nonce, if * not, it means your config responses haven't started yet. * NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. */ uint32 config_complete_id = 8; /* * Sent to tell clients the radio has just rebooted. Set to true if present. * Not used on all transports, currently just used for the serial console. * NOTE: This ID must not change - to keep (minimal) compatibility with <1.2 version of android apps. */ bool rebooted = 9; } } /* * packets/commands to the radio will be written (reliably) to the toRadio characteristic. * Once the write completes the phone can assume it is handled. */ message ToRadio { /* * In the <1.2 versions packet had ID 2, to prevent confusing old apps with our new packets, we've changed. * 101-103 were used for set_radio, set_owner, set_channel */ reserved 1, 101, 102, 103; oneof payloadVariant { /* * send this packet on the mesh */ MeshPacket packet = 2; /* * phone wants radio to send full node db to the phone, This is * typically the first packet sent to the radio when the phone gets a * bluetooth connection. The radio will respond by sending back a * MyNodeInfo, a owner, a radio config and a series of * FromRadio.node_infos, and config_complete * the integer you write into this field will be reported back in the * config_complete_id response this allows clients to never be confused by * a stale old partially sent config. */ uint32 want_config_id = 100; } }