{"id":1600,"date":"2010-07-18T13:04:13","date_gmt":"2010-07-18T11:04:13","guid":{"rendered":"http:\/\/www.alphak.net\/news\/?p=1600"},"modified":"2014-09-21T16:35:26","modified_gmt":"2014-09-21T14:35:26","slug":"backend-youpi-documentation","status":"publish","type":"post","link":"https:\/\/www.alphak.net\/news\/2010\/07\/backend-youpi-documentation\/","title":{"rendered":"Backend Youpi :: documentation"},"content":{"rendered":"

Ceux qui ont d\u00e9j\u00e0 fait un peu de code savent \u00e0 quel point il peut \u00eatre tentant de se lancer t\u00eate baiss\u00e9e<\/strong> dans un d\u00e9veloppement sans avoir pris le temps de r\u00e9fl\u00e9chir un minium au pr\u00e9alable. Et \u00e0 quel point cela peut s’av\u00e9rer une fausse bonne id\u00e9e<\/strong> lorsque le d\u00e9veloppement est d\u00e9marr\u00e9 depuis longtemps et qu’il faut reconsid\u00e9rer la moiti\u00e9 de l’impl\u00e9mentation \u00e0 cause d’une erreur de conception<\/strong>.<\/p>\n

Pour une fois, j’ai d\u00e9cid\u00e9 de suivre la voie de la sagesse, si l’on peut dire, en choisissant de poser avec soin les bases de la communication<\/strong> avec le futur backend<\/strong> du robot Youpi, et de ne pas commencer \u00e0 coder \u00e0 la h\u00e2te.<\/p>\n

Je d\u00e9voile donc dans la suite de cet article le draft de communication frontend-backend<\/strong> imagin\u00e9 ce week-end pendant quelques moments perdus. Il permet d\u00e9j\u00e0 d’avoir un bon aper\u00e7u de la mani\u00e8re d’impl\u00e9menter ces exigences dans le code.<\/p>\n

Pour ceux qui auraient tendance \u00e0 trouver ce formatage quelque peu indigeste <\/strong>(et je les comprends), une version RTF avec quelques couleurs est disponible ici : Youpi backend instruction manual (RTF)<\/a>.<\/p>\n

Title: Youpi backend instruction manual\r\nAuthor: AlphaK - www.alphak.net\r\nRevision: 2011-08-01\r\nStatus: Draft\r\n.\r\n>\r\n> GLOSSARY\r\n>\r\n.\r\nAn instruction is an order for a motor to start or stop a rotation.\r\n.\r\nAn instructionSet is a set of instructions executed simultaneously.\r\n.\r\nAn instructionChain is a set of instructionSets executed sequentially.\r\n.\r\nAn instructionChainModifier is a request to the backend for the modification of the current instructionChain.\r\n.\r\nA specialAction is a request to the backend not related to the rotation of a motor.\r\n.\r\nA command is a set of printable characters sent to the backend to order an instructionChainModifier or a specialAction.\r\n.\r\n>\r\n> SYNOPSIS\r\n>\r\n.\r\ncommand\r\n(instructionChainModifier|specialAction)\\n\r\nA command contains exactly one instructionChainModifier or one specialAction, and ends with a carriage return character (byte 0x0A, symbolized with \\n in this document for readability).\r\n.\r\nspecialAction\r\n(I|C|R)!!\r\nA specialAction contains exactly one of the I, C, R characters and ends with a double exclamation mark.\r\nI: Information request - Asks the backend to report for each motor the number of half-steps executed since the beginning of the program or the last half-step counter reset.\r\nC: Counter restet - Asks the backend to reset half-step counter.\r\nR: Re-init - Asks the backend to send the re-init instruction to the robot.\r\n.\r\ninstructionChainModifier\r\n[action!waitMode!]instructionSet\r\nAn instructionChainModifier contains an action, a waitMode parameter, and an instructionSet, separated by exclamation marks. action and waitMode are optional; instructionChainModifier defaults to C!W!instructionSet when not provided by the frontend.\r\n.\r\naction\r\nC|A|M\r\nAn action contains exactly one of the C, A, M characters.\r\nC: Cancel - The current and all the following instructionSet in the instructionChain are cancelled, and the instructionChain starts executing the provided instructionSet.\r\nA: Append - The provided instructionSet is appended at the end of the instructionChain.\r\nM: Merge - The current instructionSet in the instructionChain is merged with the provided instructionSet. Remaining instructionSets in the instructionChain are not altered. If the provided instructionSet contains instructions related to a motor for which there is no instruction in the current instructionSet, provided instructions are added to the current instructionSet. If the provided instructionSet contains instructions related to a motor for which there is already an instruction in the current instructionSet, current instructions are cancelled and replaced by provided instructions.\r\n.\r\nwaitMode\r\nW|N|D\r\nA waitMode contains exactly one of the W, N, D characters.\r\nW: Wait - Sets the instructionSet in wait mode. In that mode, the backend waits the end of all instructions of the instructionSet to consider the last is over and to execute next instructionSet. If the ordered action is M, the waitMode of the current instructionSet is replaced by the waitMode of the provided instructionSet.\r\nN: Nowait - Sets the instructionSet in nowait mode. In that mode, the backend considers the instructionSet as over as soon as the first instruction has ended. If the ordered action is M, the waitMode of the current instructionSet is replaced by the waitMode of the provided instructionSet.\r\nD: Default - If the ordered action is C or A, waitMode D defaults to W. If the ordered action is M, waitMode D does not modify the waitMode of the current instructionSet.\r\n.\r\ninstructionSet\r\ninstruction[|instruction...]\r\nAn instructionSet contains one or more instructions. Each instruction is separated by a pipe character. If an instructionSet contains several instructions related to the same motor, the instructionSet is considered invalid.\r\n.\r\ninstruction\r\nmotor,rotation,unit,value,period\r\nAn instruction contains exactly 5 parameters given in an invariable order and separated by a comma.\r\n.\r\nmotor\r\n0|1|2|3|4|5|A\r\nA motor contains exactly one of the 0, 1, 2, 3 4, 5, A characters. The provided character is related to a motor of the robot.\r\n0: Base motor\r\n1: Shoulder motor\r\n2: Elbow motor\r\n3: Wrist motor\r\n4: Hand motor\r\n5: Plier motor\r\nA: All motors\r\n.\r\nrotation\r\nL|R|N|I\r\nA rotation contains exactly one of the L, R, N, I characters. The provided character is related to a rotation order.\r\nL: Left rotation\r\nR: Right rotation\r\nN: No operation. Asks the motor to stop.\r\nI: Back to Initial state, order motors to rotate back to their initial position according to motor counters. USE WITH CAUTION!\r\n.\r\nunit\r\nH|D|S|U\r\nA unit contains exactly one of the H, D, T, U characters. The provided character is related to a unit order. If rotation is I, unit must be U.\r\nH: Half-step - Provided value represents half-steps, or steps for plier motor.\r\nD: Degrees - Provided value represents degrees. Not relevant for plier motor.\r\nS: Seconds - Provided value represents seconds.\r\nU: Unlimited - Ordered rotation has no limit. USE WITH CAUTION!\r\n.\r\nvalue\r\nFloat value, greater or equal than zero. Decimal separator is a dot '.'.\r\nThe value is provided according to the provided unit. If unit is U, value must be 0. As there is no physical or logical limits on the robot to ensure the motor does not exceed the maximum rotation angle, the frontend must ensure that provided values and unit will not damage the robot.\r\n.\r\nperiod\r\nFloat value, greater or equal than one. Decimal separator is a dot '.'.\r\nThe period affects the rotation speed for each motor. Default period is 1 and represents the maximum motor speed. The provided period is proportional to the interval of low-level orders sent to the same motor. For instance a provided period of 2 will make the motor rotate twice as slow as the maximum speed.\r\n.\r\n>\r\n> EXAMPLES\r\n>\r\n.\r\nCancel all orders and asks the base motor to rotate left over 40\u00b0 at maximum speed:\r\nC!W!0,L,D,40,1\\n\r\n.\r\nAppends the order for the shoulder motor to rotate right during 5.2 seconds with 1/3 of maximum speed:\r\nA!W!1,R,S,5.2,3\\n\r\n.\r\nImmediately cancel all orders, asks all motors to stop for an unlimited duration:\r\nC!W!A,N,U,0,1\\n\r\n.\r\nCancel all orders and asks elbow and wrist motors to rotate simultaneously 150 half-steps each:\r\nC!W!2,R,H,150,1|3,L,H,150,1\\n\r\n.\r\nAdds the order for the base motor to rotate 600 half-steps at half speed meanwhile other motors are already rotating:\r\nM!D!0,L,H,600,2\\n\r\n.\r\nPuts back base motor into initial position at 1/4 speed:\r\nC!W!0,I,U,0,4\\n\r\n.<\/pre>\n
Quelques explications suppl\u00e9mentaires<\/strong> en plus du pav\u00e9 ci-dessus :<\/p>\n
Le backend s’attend \u00e0 recevoir une commande par ligne. Une commande permet de mettre en mouvement ou arr\u00eater un seul ou plusieurs moteurs. Gr\u00e2ce aux diff\u00e9rents en-t\u00eates des instructionChainModifiers, le robot sera pilotable en mode temps r\u00e9el<\/strong> (interactions directes avec l’utilisateur via le frontend), ou script\u00e9 <\/strong>(une flopp\u00e9e de commandes fournie au d\u00e9marrage ou graduellement, et le robot ex\u00e9cute le tout). J’ai \u00e9galement pr\u00e9vu un l\u00e9ger reporting <\/strong>afin que l’utilisateur puisse connaitre la position de chaque moteur depuis une origine et ainsi \u00e9tablir plus facilement ses commandes si un pilotage script\u00e9 est d\u00e9sir\u00e9.<\/p>\n
Le diagramme <\/strong>suivant permet d’avoir un meilleur aper\u00e7u des possibilit\u00e9s th\u00e9oriques du backend. Chaque ligne correspond \u00e0 un moteur. En abscisses, le temps. Chaque subdivision correspond \u00e0 une seconde. Une barre horizontale bleue situ\u00e9e sur une ligne indique la rotation du moteur correspondant. En bleu figurent \u00e9galement les commandes, ainsi que le moment o\u00f9 elles sont envoy\u00e9es au backend. Les instructionSets qui composent l’instructionChain sont encadr\u00e9s en rouge.<\/p>\n
\"Diagramme<\/a>
Diagramme de commandes<\/p><\/div>\n
Voila l’\u00e9tat d’avancement actuel. Il s’agit de ce que je consid\u00e8re actuellement comme un ensemble \u00ab\u00a0id\u00e9al\u00a0\u00bb de fonctionnalit\u00e9s. Ces exigences sont encore \u00e0 l’\u00e9tat de draft et pourront \u00e9voluer dans le futur en fonction des diff\u00e9rents commentaires et remarques. Pour ce qui est de l’impl\u00e9mentation, j’imagine que \u00e7a se fera par \u00e9tapes en fonctions des priorit\u00e9s.<\/p>\n","protected":false},"excerpt":{"rendered":"
Ceux qui ont d\u00e9j\u00e0 fait un peu de code savent \u00e0 quel point il peut \u00eatre tentant de se lancer t\u00eate baiss\u00e9e<\/strong> dans un d\u00e9veloppement sans avoir pris le temps de r\u00e9fl\u00e9chir un minium au pr\u00e9alable. Et \u00e0 quel point cela peut s’av\u00e9rer une fausse bonne id\u00e9e<\/strong> lorsque le d\u00e9veloppement est d\u00e9marr\u00e9 depuis longtemps et qu’il faut reconsid\u00e9rer la moiti\u00e9 de l’impl\u00e9mentation \u00e0 cause d’une erreur de conception<\/strong>.<\/p>\n
Pour une fois, j’ai d\u00e9cid\u00e9 de suivre la voie de la sagesse, si l’on peut dire, en choisissant de poser avec soin les bases de la communication<\/strong> avec le futur backend<\/strong> du robot Youpi, et de ne pas commencer \u00e0 coder \u00e0 la h\u00e2te.<\/p>\n\t
\r\n\t\t
\r\n\t\t\t[<\/span>…<\/span>]<\/span>\r\n\t\t<\/div>\r\n\t\t
\r\n\t\t\tLire la suite de l'article <\/i><\/span><\/a>\r\n\t\t<\/div>\r\n\t\t<\/a>\r\n\t<\/div>\r\n","protected":false},"author":1,"featured_media":1620,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[142],"tags":[211,343,215,214,144],"class_list":["post-1600","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-bricolage","tag-backend","tag-code","tag-documentation","tag-manpage","tag-youpi"],"_links":{"self":[{"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/posts\/1600"}],"collection":[{"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/comments?post=1600"}],"version-history":[{"count":7,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/posts\/1600\/revisions"}],"predecessor-version":[{"id":2908,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/posts\/1600\/revisions\/2908"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/media\/1620"}],"wp:attachment":[{"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/media?parent=1600"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/categories?post=1600"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.alphak.net\/news\/wp-json\/wp\/v2\/tags?post=1600"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}