Bluetooth / Radio communication between bots!

[Woonters]

This should close #52

There's still some stuff I think might be worth doing:

[ ] - Review current message implementation, is the message size, style etc. worth it?
[ ] - Calculate the cooldown values and adjust them a for balancing
[ ] - Should the write buffer have better write functionality? I would consider using an offset from MEM_BLUETOOTH and writing each 4 bytes instead of just sending 1 byte at a time, this would probably mean you should be able to read from it as well, effectively treat it like a memory location
[ ] - Check over all the names for interfacing functions in kartoffel::bluetooth
[ ] - Add wider / better tests
[ ] - Tutorial level

Other notes

I added two test bots Ianthe and Coronabeth, happy to delete them, but thought if I was going to do a tutorial level they might be useful currently they just work as a tx rx pair doing nothing else

I'd certainly be interested in other messaging concepts as well, creating a send / receive stream between two bots for instance could be a fun task

I think when writing this there was a small part of my brain always thinking about electronic warfare, it'd be cool if you could do some sort of that in a way, but also probably really messy, I made the bots send their own ID as part of the message, but if you wanted to encourage people to write their own clever networking code then maybe the bot id section could be dropped (and i'd probably increase the Message length to accommodate

[Patryk27]

Thanks for the pull request - I like the direction and, having thought about it for a couple of days, I think we could take it a couple of steps further!

Note that everything below is a proposal, a bag of thoughts - feel free to comment, come up with counter-ideas, and so on.

---

Overall, I tend for each peripheral to be somewhat different from each other not only in the tangible functionality, but also the intrinsic mechanic -- serial drops older bytes, compass auto-refreshes in the background etc.

For Bluetooth (aka radio, and we'll get to the naming soon) the mechanic we could apply to make it intrinsically different from radar is to make it possible to send messages without specifying the radius. Rather, the message travels outwards from the bot and with every tick it travels, it wanes, increasing the chance for observing bit flip(s) within it.

(in a similar spirit -- when two messages collide mid-air, both can get mangled, which touches on the electronic warfare subject you mentioned.)

Practically speaking, instead of having send_bluetooth(radius), we'd have radio_send(msg) that emits given message outwards, propagating it with some constant speed, say 1 tile every 256 world-ticks:

  .

->

  .
 . .
  .

->

  .
 . .
.   .
 . .
  .

When a message "hits" a bot, that's when it's pushed onto the radio's "message stack" (if there's space for it), with some of the bits mangled (maybe 1 bit for each 1 traversed tile? though it would certainly make much more sense to apply inverse square law here so that messages received in close proximity have almost 100% chance of being correct).

Naming

I'm feeling radio more than Bluetooth - that's because Bluetooth kinda implies a high-level thing going on (with device discovery etc. provided by the protocol), while what we'd like to offer is more of a "send a bag of bytes and receive a bag of bytes" functionality.

In particular, I'd like to incentivize players to implement error recovery algorithms (Hamming code and whatnot) and higher-level protocols on top of the basic tools provided for the game.

Interface

As with everything in here, the interface here is also a proposal - a sketched version of my thoughts is:

// N.B. we could assume that radio is always turned on, but at some point I'd
//      like to revisit the concept of implementing a battery - turning the 
//      radio on/off could be a battery-saving strategy then
pub fn radio_on() {
    // N.B. we're reserving 0x01 as a general "set radio power" command - in the
    //      future we could have a "set_radio_power()" function that would cause
    //      the radio to eat more battery in exchange for allowing it to send
    //      messages for longer distances (and vice versa - reduce the chance of
    //      observing a bit flip in a retrieved message)
    //
    //      this would be then implemented as cmd(0x01, power, 0x00, 0x00)
    wri(MEM_RADIO, 0, cmd(0x01, 0x01, 0x00, 0x00));
}

pub fn radio_off() {
    wri(MEM_RADIO, 0, cmd(0x01, 0x00, 0x00, 0x00));
}

pub fn radio_status() -> u32 {
    rdi(MEM_RADIO, 0)
}

pub fn is_radio_on() -> bool {
    radio_status() & 1 > 0
}

// aka "can we send the next packet"
pub fn can_radio_send() -> bool {
    radio_status() & 2 > 0
}

// aka "is there any packet waiting for us in the queue"
pub fn can_radio_recv() -> bool {
    radio_status() & 4 > 0
}

pub fn radio_send(msg: &[u8; 32]) {
    for (idx, payload) in msg.array_windows().enumerate() {
        wri(MEM_RADIO, idx + 1, u32::from_le_bytes(payload));
    }

    wri(MEM_RADIO, 0, cmd(0x02, 0x00, 0x00, 0x00));
}

// if there's no packet, just fills msg with zeros
pub fn radio_recv(msg: &mut [u8; 32]) {
    for (idx, payload) in msg.array_windows_mut().enumerate() {
        *msg = rdi(MEM_RADIO, idx + 1).to_le_bytes();
    }
}

// Shiny thing! Allows to specify a predicate for radio_recv().
//
// E.g. calling `radio_filter(&[0xca, 0xfe, 0xba, 0xbe])` will cause the radio
// to transparently ignore all incoming messages which have a different prefix;
// doesn't affect `radio_send()`.
//
// This pairs up with `radio_send()` *not* allowing to send a message to a
// specific robot id -- rather, players are encouraged to come up with a
// "namespacing" scheme of their own.
//
// For instance - if someone wants to have a direct bot-to-bot connection, they
// can prefix their messages with the bot id (or rather a hash of it / half of
// it, since we purposefully keep the prefix shorter than a full bot id).
//
// Alternatively - if someone wants to form a bot-cluster and communicate within
// it instead of directly to a specific bot, they can just randomize a 32-bit
// number and use it to prefix the messages.
//
// Even more combinations exist, e.g. the prefix could encode a message type so
// that you can have different bots deployed on the field that respond respond
// only to their own specific message type (which is sort of a variation on the
// clustering mechanism above, now that I think about it).
pub fn radio_filter(prefix: &[u8; 4]) {
    wri(MEM_RADIO, 0, cmd(0x03, 0x00, prefix[0], prefix[1]));
    wri(MEM_RADIO, 0, cmd(0x03, 0x01, prefix[2], prefix[3]));
}

Tutorial

I think the tutorial is plenty long as it is - instead of introducing more chapters (which could be frustrating for people who want to just grasp the basics), we could introduce a new challenge.

I was thinking a distributed key-value database? 👀

You'd have to implement a couple of bots that together form a cluster that's able to respond to basic queries such as "put foo=bar" or "get foo" (those would also get transmitted to your robot over the radio from a built-in challenge-robot).

You'd be forced to implement more than one robot simply because the challenge-robot would generate over 128 kB of random queries - so you would have to keep multiple robots working together, so that each robot contains its own "set" (shard?) of the database, otherwise you wouldn't be able to respond back to all of the queries asked by the challenge-bot.

In the extreme version we could force the robots to fight with some enemies - this way you'd be forced to implement some kind of storage redundancy; but that's maybe for another day.

Open questions

radio_filter() vs bitrot

If messages are applicable to this "distance bitrot", then it would make sense for each bit of the message to be equally likely to get flipped - and this can make it frustrating to use radio_filter(), because when configured for filter 0xcafebabe, it would reject a message that begins with 0xcaffbabe, even though that message could well be meant for the robot.

(i.e. the specific problem is that radio_filter() isn't error-recovery-aware - and it cannot be, since it'd be implemented within the game itself)

A non-realistic (I think?) but good-enough solution could be to penalize further bits more than the initial bits, something like:

fn mangle_message(msg: &mut [Bit; 256], prob: f32) {
    for (idx, bit) in msg.iter_mut().enumerate() {
        let bit_prob = (*idx as f32 / 128.0).clamp(0.0, 1.0) * prob;
        
        if rng.gen(bit_prob) {
            *bit = bit.flip();
        }
    }
}

Intuitively, when calling mangle_message(..., 0.1) we'd expect for 10% of the bits to be mangled, just skewed towards the end of the message instead of uniformly throughout it; this wouldn't make radio_filter() bulletproof, but it'd make it more fun and practical to use, I think.

Message size vs cooldown vs challenge

If we're able to send just 32b of payload, then the whole "challenge requires you to handle hundredths of kilobytes of queries" part might take solid minutes to complete, mostly waiting for the queries to be sent/received (= no fun).

On the other hand, forcing messages to be e.g. 128b can also be wasteful (those bytes need to be copied into MMIO, after all).

Maybe a good compromise would be to allow to send messages of arbitrary length? (but more than 4b, to match the prefix, and less than 128b, not to overflow the receiving part)

This would be sort of "pay as you go" mechanism: you want to send a short message? cool; you want to send a longer message? cool, but you have to wait a bit longer.

Next steps

Alright, this turned out to be quite a message! Feel free to treat is as an RFC - nothing here is set in stone, it's just a couple of ideas.

In terms of the implementation, nothing here shouts terribly difficult to me - if you'd want to give it a stab, I'd love to support and review! If you don't have much time or ain't feeling like implementing more at the moment, that's also fine, just lemme know.

(but as I said, I think it's a nice, moderately challenging project that should be also quite rewarding; I've got a couple of blog posts to write myself, so I can't complain for lack of work at the moment either 😄)

Implementation hints

Assuming that the basic idea here stands, we'd have to store messages into the world itself:

kartoffels/app/crates/kartoffels-world/src/lib.rs

Line 167 in 9e7a6f9

fn create_world(res: Resources) -> World {

Something akin to:

struct Messages {
    message: Vec<Message>,
}

struct Message {
    emitted_at: IVec2,
    radius: i32,
}

Then we'd have to create a new system be responsible for propagating those messages, checking when they collide with bots, and putting them into bots' recv queues (performing the radio_filter() check, bitrot mechanism etc.):

kartoffels/app/crates/kartoffels-world/src/lib.rs

Line 265 in 9e7a6f9

fn main_schedule() -> Schedule {

Something like:

fn receive_messages(messages: ResMut<Messages>, bots: ResMut<AliveBots>) {
    let mut msgs_to_delete = Vec::new();
    
    for (msg_idx, msg) in messages.iter_mut().enumerate() {
        for bot in bots {
            // Having `O(n * m)` isn't ideal, especially since this comparison
            // will necessarily return _false_ most of the time, but it's a good
            // starting point
            if bot.pos.distance(msg.emitted_at) == message.radius {
                bot.msgs.receive(msg);
            }
        } 
        
        msg.radius += 1; // possibly every 128 world ticks or so, depending on what's more fun in practice

        if msg.radius >= 32 { // possibly even further apart, depending on how it turns out in practice
            msgs_to_delete.push(msg_idx);
        }
    }
    
    /* ... */
}

Eventually messages should also be persisted into the savefile:

kartoffels/app/crates/kartoffels-world/src/storage/systems/save.rs

Line 71 in 9e7a6f9

let world = SerializedWorld {

... but for development you can start off with Messages::default().

[Woonters]

Hi really like all of these ideas, and I think you've hit the nail on the head with practically all of them
I'm happy to go about implementing all of this, only really with one or two questions.

1.

If we are doing the different message sizes from 4 to 128 Bytes then should the recieve buffer still be 5 messages long?
I think the filter mainly deals with the issue of message spam, but still it feels a shame that a radio module would have it's buffer filled all the same from 20B and 512B

2.

With the comment on message mangling:

"(in a similar spirit -- when two messages collide mid-air, both can get mangled, which touches on the electronic warfare subject you mentioned.)"

Would it be worth considering the strength of the sent message as to how much it mangles / gets mangled

[Patryk27]

should the recieve buffer still be 5 messages long?

Yeah, that'd be a pity - I think a size-limited buffer makes more sense (e.g. 512b?).

Now that I think about it, dynamically-sized messages require changing the API as well, maybe something like:

pub fn radio_send(msg: &[u8]) {
    /* ... */
}

// high-level function
pub fn radio_recv() -> Vec<u8> {
    // would be much better to use MaybeUninit, just sketching a general concept
    let mut msg = vec![0; radio_recv_len()];
    radio_recv_msg(&mut msg):
    msg
}

// low-level function: returns the length of the next pending message (or 0, if there's none)
pub fn radio_recv_len() -> usize {
    /* ... */
}

// low-level function: fills msg with the pending message (requires extra care if msg.len() % 4 != 0, same as radio_send())
pub fn radio_recv_msg(msg: &mut [u8]) {
    /* ... */
}

Would it be worth considering the strength of the sent message as to how much it mangles / gets mangled

I think so!

Currently we can only define strength in terms of message distance (further apart from emitted_at = weaker), but in the future we could incorporate that set_radio_power() concept that'd affect the mangling as well.