رابط الرسالة

مقدمة

تتيح فئة message_link لروبوتين من نوع V5 Brains التواصل عبر إرسال رسائل نصية قصيرة مع بيانات صغيرة اختيارية. وهي مصممة لتنسيق الروبوتات فيما بينها، مثل بدء الإجراءات الروتينية، ومشاركة نتائج المستشعرات، أو تحفيز سلوكيات معينة على روبوت آخر.

كل استخدام للأمر send يُضيف رسالة إلى قائمة انتظار وحدة المعالجة V5 Brain المرتبطة، وتُقرأ قائمة الانتظار وفقًا لأسلوب “الوارد أولًا يُخرج أولًا” (FIFO). إذا أُرسلت عدة رسائل قبل أن تستخدم وحدة المعالجة V5 Brain الأخرى الأمر receive، فسيتم تخزينها وإعادتها واحدة تلو الأخرى بالترتيب الذي أُرسلت به. نظرًا لإمكانية تراكم الرسائل في قائمة الانتظار، فإن إرسال الحالة نفسها بشكل متكرر في كل دورة قد يُؤدي إلى تراكم الرسائل؛ لذا، بالنسبة للمنطق الحساس للوقت، يُنصح بالإرسال فقط عند تغيير القيم.

هام: يجب أن يقوم كلا الروبوتين بتشغيل مشاريع تستخدم message_link في نفس الوقت، وإلا فلن يتم إرسال/استقبال أي رسائل.

مُنشئات الفئات

message_link( 
  int32_t     index, 
  const char  *name, 
  linkType    type, 
  bool        isWired = false );

مُدمِّر الفئة

يقوم بتدمير الكائن message_link وتحرير الموارد المرتبطة به.

virtual ~message_link();

حدود

المعلمة	يكتب	وصف
index	int32_t	المنفذ الذكي الذي يتصل به راديو V5 أو الكابل الذكي، مكتوبًا على النحو التالي: PORTx، حيث x هو رقم المنفذ (على سبيل المثال، PORT1).
name	char	اسم رابط الرسالة.
type	linkType	نوع الرابط، إما linkType::manager أو linkType::workerتُستخدم هذه المعلومات لضبط الراديو بشكل صحيح، كما تُحدد عرض النطاق الترددي المتاح للإرسال والاستقبال. يمتلك الروبوت المدير ضعف عرض النطاق الترددي المتاح (1040 بايت/ثانية) لإرسال المعلومات إلى الروبوت العامل (520 بايت/ثانية). linkType::manager - كائن message_link هو مدير. linkType::worker - كائن message_link هو عامل.
isWired	bool	ما إذا كان كائن message_link متصلاً سلكياً. true - كائن message_link متصل سلكياً. false - كائن message_link لاسلكي.

مثال

كود للروبوت 1

// Create a wireless link in Port 1
message_link link = message_link(
  PORT1, // index
  "VEXRoboticsLink123456789", // name
  linkType::manager, // type
  true); // isWired

كود للروبوت 2

// Create a wireless link in Port 1
message_link link = message_link(
  PORT1, // index
  "VEXRoboticsLink123456789", // name
  linkType::worker, // type
  true); // isWired

الدوال الأعضاء

تتضمن فئة message_link الدوال الأعضاء التالية:

• isLinked — تُرجع ما إذا كان هذا الدماغ متصلاً بشكل فعال بالدماغ المقترن به.

• send — يرسل رسالة إلى الدماغ المقترن.

• receive — ينتظر ويعيد الرسالة الواردة التالية.

• received — يسجل دالة ليتم استدعاؤها كلما تم استلام رسالة جديدة.

قبل استدعاء أي من الدوال الأعضاء في message_link message_link يجب إنشاء مثيل message_link ، كما هو موضح أدناه:

كود للروبوت 1

// Create a wireless link in Port 1
message_link link = message_link(
  PORT1, // index
  "VEXRoboticsLink123456789", // name
  linkType::manager, // type
  true); // isWired

كود للروبوت 2

// Create a wireless link in Port 1
message_link link = message_link(
  PORT1, // index
  "VEXRoboticsLink123456789", // name
  linkType::worker, // type
  true); // isWired

isLinked

isLinked طريقة تُرجع ما إذا كانت وحدات V5 Brains الموجودة على MessageLink مقترنة ببعضها البعض.

Available Functions

bool isLinked();

Parameters

لا تحتوي هذه الدالة على أي معلمات.

Return Values

تُرجع هذه الدالة قيمة منطقية (boolean).

• true - تم إقران جهازي V5 Brains ويتواصلان عبر هذا الرابط.

• false - لم يتم إقران جهازي V5 Brains على هذا الرابط.

Notes

من الممارسات الجيدة التحقق دائمًا من ربط V5 Brains في بداية المشروع قبل تشغيل أي كود إضافي.

Examples

كود للروبوت 1

// Tell the other robot when the screen is being pressed
  // Create the link
  message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::manager, true);

  // Do not run code UNTIL the Brains are linked
  while (!link.isLinked()){
    wait(0.1, seconds);
  }

  Brain.Screen.print("Robot 1 - Manager");

  // Continuously send if the screen is being pressed
  while (true){
    if (Brain.Screen.pressing()){
      link.send("pressed");
    } else {
      link.send("released");
    }
    wait(0.05, seconds);
  }

كود للروبوت 2

// Display if the other robot's screen is being pressed

  // Create the link
  message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::worker, true);
  
  // Do not run code UNTIL the Brains are linked
  while (!link.isLinked()){
   wait(0.1, seconds);
  }

  // Continuously check if Robot 1 has sent "pressed"
  while (true){
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);
    Brain.Screen.print("Robot 2 - Worker");
    Brain.Screen.newLine();
    char msg[32] = {0};                         // buffer for incoming message
    int32_t n = link.receive(msg, sizeof(msg), 100);  // wait up to 100ms
    if (n > 0 && strcmp(msg, "pressed") == 0) {
      Brain.Screen.newLine();
      Brain.Screen.print("Manager is being pressed!");
    }
    wait(0.05, seconds);
  }

send

يرسل رسالة عبر اتصال الرابط.

Available Functions

1 — يرسل سلسلة رسائل.

int32_t send( 
  const char *message );

2 — يرسل سلسلة رسائل تحتوي على double.

int32_t send( 
  const char *message, 
  double      value );

3 — يرسل سلسلة رسالة تحتوي على int32_t و double.

int32_t send(
  const char *message, 
  int32_t     index, 
  double      value );

Parameters

المعلمة	يكتب	وصف
message	const char*	الرسالة المراد إرسالها إلى وحدة الدماغ V5 المرتبطة الأخرى.
index	int32_t	عدد صحيح لإرساله إلى وحدة الدماغ V5 الأخرى المرتبطة.
value	double	عدد عشري مزدوج لإرساله إلى وحدة V5 Brain الأخرى المرتبطة. يتم تنسيق الأعداد العشرية المزدوجة إلى 4 منازل عشرية؛ إذا تم توفير عدد أقل من المنازل العشرية، تتم إضافة أصفار لاحقة حتى يتم عرض 4 منازل عشرية.

Return Values

هذه الدالة لا تُرجع أي قيم.

Notes

إذا تم إرسال الرسالة message فقط، فإن وحدة V5 Brain الأخرى المرتبطة بها تتلقى تلك الرسالة بالضبط.

إذا تم تضمين القيمة value (والقيمة index إذا تم توفيرها)، فإن الدماغ المستقبل يتلقى رسالة مشفرة واحدة تجمع جميع الحقول بهذا الترتيب: .message_index_value

Examples

باستخدام link.send(“string”, 1, 2.55) كـ .string_1_2.5500.

كود للروبوت 1

// Tell the other robot when the screen is being pressed

// Create the link
message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::manager, true);

// Do not run code UNTIL the Brains are linked
while (!link.isLinked()){
  wait(0.1, seconds);
}

Brain.Screen.print("Robot 1 - Manager");

// Continuously send if the screen is being pressed
while (true){
  if (Brain.Screen.pressing()){
    link.send("pressed");
  } else {
    link.send("released");
  }
  wait(0.05, seconds);
}

كود للروبوت 2

// Display if the other robot's screen is being pressed

// Create the link
message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::worker, true);

// Do not run code UNTIL the Brains are linked
while (!link.isLinked()){
  wait(0.1, seconds);
}
// Continuously check if Robot 1 has sent "pressed"
while (true){
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Robot 2 - Worker");
  Brain.Screen.newLine();
  char msg[32] = {0};  // buffer for incoming message
  int32_t n = link.receive(msg, sizeof(msg), 100);  // wait up to 100ms
  if (n > 0 && strcmp(msg, "pressed") == 0) {
    Brain.Screen.newLine();
    Brain.Screen.print("Manager is being pressed!");
  }
  wait(0.05, seconds);
}

receive

يستقبل رسالة من اتصال الرابط.

Available Functions

int32_t receive(
  char     *buffer,
  int32_t   length, 
  int32_t   timeoutMs = 500 );

Parameters

المعلمة	يكتب	وصف
buffer	char*	المخزن المؤقت لتخزين الرسالة المستلمة.
length	int32_t	طول المخزن المؤقت.
timeoutMs	int32_t	How long in milliseconds receive will wait for a new message only if the queue is empty. Default is 300,000 (300 seconds).

Return Values

تقوم هذه الدالة بإرجاع عدد البايتات المستلمة.

Notes

• receive returns the next queued message from the other linked V5 Brain. Messages are read in FIFO order (oldest unread first). If the queue is empty when receive is called, it waits up to the specified timeout for a new message. If no message arrives in that window, receive returns 0, and any message sent afterward remains in the queue to be read the next time receive is used.

• إذا أرسل جهاز V5 Brain المرتبط الآخر سلسلة stringو receive ويعيدان تلك السلسلة بالضبط.

• إذا أرسل معالج V5 Brain الآخر المرتبط عددًا صحيحًا و/أو عددًا عشريًا، فإن receive ، ويعيد سلسلة مشفرة واحدة تجمع جميع الحقول بهذا الترتيب: .string_integer_float

  • على سبيل المثال، إذا استخدم معالج V5 المرتبط الآخر الدالة link.send(“string”, 1, 2.55)، فإن استخدام الدالة link.receive() يُعيد سلسلة مُشفّرة مثل .string_1_2.5500. يمكنك تقسيم هذه السلسلة المُشفّرة (انظر الأمثلة أدناه) لاستخراج اسم الرسالة، والقيم الصحيحة، والقيم العشرية.

  • إذا كنت تفضل تجنب التقسيم/التحليل اليدوي، فاستخدم received لتسجيل معالج لاسم رسالة معين؛ يتلقى المعالج القيم المرسلة كوسائط.

Examples

باستخدام link.send(“string”, 1, 2.55) كـ .string_1_2.5500.

كود للروبوت 1

// Tell the other robot when the screen is being pressed

// Create the link
message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::manager, true);

// Do not run code UNTIL the Brains are linked
while (!link.isLinked()){
  wait(0.1, seconds);
}

Brain.Screen.print("Robot 1 - Manager");

// Continuously send if the screen is being pressed
while (true){
  if (Brain.Screen.pressing()){
    link.send("pressed");
  } else {
    link.send("released");
  }
  wait(0.05, seconds);
}

كود للروبوت 2

// Display if the other robot's screen is being pressed

// Create the link
message_link link = message_link(PORT1, "VEXRoboticsLink123456789", linkType::worker, true);

// Do not run code UNTIL the Brains are linked
while (!link.isLinked()){
  wait(0.1, seconds);
}
// Continuously check if Robot 1 has sent "pressed"
while (true){
  Brain.Screen.clearScreen();
  Brain.Screen.setCursor(1, 1);
  Brain.Screen.print("Robot 2 - Worker");
  Brain.Screen.newLine();
  char msg[32] = {0};   // buffer for incoming message
  int32_t n = link.receive(msg, sizeof(msg), 100);  // wait up to 100ms
  if (n > 0 && strcmp(msg, "pressed") == 0) {
    Brain.Screen.newLine();
    Brain.Screen.print("Manager is being pressed!");
  }
  wait(0.05, seconds);
}

received

يسجل وظيفة ليتم استدعاؤها كلما استقبلت وحدة المعالجة المركزية V5 رسالة مرسلة.

Available Functions

1 يسجل رد نداء لجميع الرسائل المستلمة (الرسالة + القيمة).

void received(
    void (* callback)(const char *, const char *, double)
);

2 يسجل رد نداء لجميع الرسائل المستلمة (الرسالة + الفهرس + القيمة).

void received(
    void (* callback)(const char *, const char *, int32_t, double)
);

3 يسجل رد اتصال لرسالة محددة (الرسالة + القيمة).

void received(
    const char *message,
    void      (* callback)(const char *, const char *, double)
);

4 يسجل رد نداء لرسالة محددة (الرسالة + الفهرس + القيمة).

void received(
    const char *message,
    void      (* callback)(const char *, const char *, int32_t, double)
);

Parameters

المعلمة	يكتب	وصف
message	const char *	اسم الرسالة المراد الاستماع إليها. في حال عدم تحديده، يتم تشغيل دالة الاستدعاء لجميع الرسائل المستلمة.
callback	void (*)(const char *, const char , double) or void ()(const char *, const char *, int32_t, double)	دالة يتم تنفيذها عند استلام رسالة.

Return Values

هذه الدالة لا تُرجع أي قيم.

Callback Signature

1 يستقبل اسم المرسل واسم الرسالة والقيمة.

void callback(const char *, const char *, double)

2 يستقبل اسم المرسل، واسم الرسالة، والفهرس، والقيمة.

void callback(const char *, const char *, int32_t, double)

يكتب	وصف
1st const char *	اسم رابط المرسل.
2nd const char *	اسم الرسالة المستلمة.
int32_t	الفهرس المرتبط بالرسالة.
double	القيمة المرتبطة بالرسالة.

Examples

كود للروبوت 1

// Create the link.
message_link link(PORT1, "LeftRightLink", linkType::manager, true);

// Send whether screen is pressed on left or right.
void screen_pressed() {
  if (Brain.Screen.xPosition() < 240) {
    link.send("left");
  } else {
    link.send("right");
  }
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();
  
  // Do not run code UNTIL the Brains are linked.
  while (!link.isLinked()) {
    wait(0.1, seconds);
  }

  Brain.Screen.print("Robot 1 - Manager");

  Brain.Screen.pressed(screen_pressed);

  while (true) {
    wait(10, msec);
  }
}

كود للروبوت 2

// Create variable to track where screen is pressed.
int lastPress = 0;

// Update the variable whenever a new message is received.
void message_received(const char* message, const char* linkname, double timestamp) {
  if (strcmp(message, "left") == 0)  lastPress = 1;
  if (strcmp(message, "right") == 0) lastPress = 2;
}

int main() {
  /* vexcodeInit() is only required when using VEXcode.
  Remove vexcodeInit() if compiling in VS Code. */
  vexcodeInit();

  // Create the link.
  message_link link(PORT1, "VEXRoboticsLink123456789", linkType::worker, true);

  // Do not run code UNTIL the Brains are linked.
  while (!link.isLinked()) {
    wait(0.1, seconds);
  }

  link.received(message_received);

  // Display if Robot 1's screen was pressed on the left or right
  while (true) {
    Brain.Screen.clearScreen();
    Brain.Screen.setCursor(1, 1);
    Brain.Screen.print("Robot 2 - Worker");
    Brain.Screen.newLine();

    if (lastPress == 1) {
      Brain.Screen.print("Manager pressed LEFT");
    } else if (lastPress == 2) {
      Brain.Screen.print("Manager pressed RIGHT");
    } else {
      Brain.Screen.print("Waiting...");
    }

    wait(0.1, seconds);
  }
}